{
  "openapi": "3.1.0",
  "info": {
    "title": "OhMy.xin Open Platform API",
    "version": "1.0.0",
    "summary": "Read-only access to publicly visible OhMy.xin circles, trading signals, and livestreams.",
    "description": "The OhMy.xin open platform exposes part of the platform to external systems over an API.\n\nCreate an API account and API keys on the website, then call the endpoints below. Authentication, rate limiting, cursor pagination, response envelopes, and call logging are handled by the platform — every endpoint inherits the same contract.\n\n**Authentication.** Every endpoint except `GET /health` requires a bearer key: `Authorization: Bearer omx_live_<8-char-id>_<32-char-secret>`. The full secret is shown exactly once at creation; the platform stores only a one-way digest. A disabled or revoked key — or a disabled or frozen account — makes the next request return `401`.\n\n**Response envelope.** Successes return `data`; failures return `error`. Both carry `meta.request_id`, which also appears in the `X-Request-Id` response header.\n\n**Rate limits.** 60 requests per minute per API account by default (the effective value is returned by `GET /me`). A per-IP fallback bucket (300 per minute by default) additionally caps all `/api/` traffic from one source IP.\n\n**Pagination.** List endpoints use cursor pagination. Send `limit` (1-100, default 20) and, for the next page, the opaque `meta.pagination.next_cursor` back as the `cursor` parameter. The cursor is bound to the `sort` used to produce it; changing `sort` invalidates it and returns `400`.\n\n**Visibility.** Only publicly visible content is returned. Paid-and-closed circles expose neither their strategies nor their lives to the strategies endpoint; the lives endpoint accepts any public circle. See each endpoint's description for the exact rules.",
    "contact": {
      "name": "OhMy.xin Developer API",
      "url": "https://docs.ohmy.xin/open-platform/"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://ohmy.xin/"
    }
  },
  "servers": [
    {
      "url": "https://ohmy.xin/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Service",
      "description": "Service health and credential self-check."
    },
    {
      "name": "Strategies",
      "description": "Publicly visible trading signals."
    },
    {
      "name": "Lives",
      "description": "Publicly visible circle livestreams."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["Service"],
        "summary": "Health check",
        "description": "Confirms the service is reachable. No authentication required.",
        "operationId": "getHealth",
        "security": [],
        "responses": {
          "200": {
            "description": "The service is reachable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthEnvelope" },
                "examples": {
                  "ok": {
                    "summary": "Healthy",
                    "value": {
                      "data": {
                        "status": "ok",
                        "version": "v1",
                        "timestamp": "2026-11-15T22:15:00+08:00"
                      },
                      "meta": {
                        "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/me": {
      "get": {
        "tags": ["Service"],
        "summary": "Credential self-check",
        "description": "Returns the API account and key behind the presented credential. Useful for verifying a key right after it is generated.",
        "operationId": "getMe",
        "responses": {
          "200": {
            "description": "The credential is valid and active.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MeEnvelope" },
                "examples": {
                  "active": {
                    "summary": "Active key",
                    "value": {
                      "data": {
                        "account": {
                          "number": "8392014",
                          "name": "Production Integration",
                          "state": "active",
                          "rate_limit_per_minute": 60
                        },
                        "key": {
                          "name": "Primary Key",
                          "masked_token": "omx_live_xxxxxxxx••••••••xxxx",
                          "state": "active",
                          "last_used_at": "2026-11-15T22:14:12+08:00"
                        }
                      },
                      "meta": {
                        "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/strategies": {
      "get": {
        "tags": ["Strategies"],
        "summary": "List publicly visible trading signals",
        "description": "Returns the publicly visible trading signals (strategy cards) across the platform: symbol, side, entry/target/stop price, take-profit ladder, plus the owning circle and the publisher's display details.\n\n**Visibility.** A signal is returned only when all of the following hold:\n\n1. its state is `running`, `take_profit`, or `stop_loss`;\n2. it has been published (`published_at` is set);\n3. it carries no member-tier gate and its audience is public (`everyone`);\n4. its circle is bound to Mixin, not dormant, set to public, and either **free** or browsable in **teaser** mode — strategies from circles that are paid *and* closed to browsing never appear.\n\nPrices are returned as strings with trailing zeros stripped (`65000.00` becomes `\"65000\"`). Convert before doing arithmetic.",
        "operationId": "listStrategies",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order. The cursor is bound to this value.",
            "schema": {
              "type": "string",
              "enum": ["published_at:desc", "updated_at:desc"],
              "default": "published_at:desc"
            }
          },
          { "$ref": "#/components/parameters/CircleNumber" },
          {
            "name": "symbol",
            "in": "query",
            "description": "Filter by trading symbol. Case-insensitive — `BTC` and `btc` are equivalent.",
            "schema": { "type": "string", "maxLength": 32 }
          },
          {
            "name": "side",
            "in": "query",
            "description": "Filter by direction.",
            "schema": { "type": "string", "enum": ["long", "short"] }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Filter by state, comma-separated.",
            "schema": {
              "type": "string",
              "enum": ["running", "take_profit", "stop_loss"],
              "default": "running,take_profit,stop_loss"
            }
          },
          {
            "name": "published_after",
            "in": "query",
            "description": "Lower bound on `published_at` (inclusive). Must be earlier than or equal to `published_before`.",
            "schema": { "type": "string", "format": "date-time" }
          },
          {
            "name": "published_before",
            "in": "query",
            "description": "Upper bound on `published_at` (inclusive). Must be later than or equal to `published_after`.",
            "schema": { "type": "string", "format": "date-time" }
          },
          { "$ref": "#/components/parameters/UpdatedAfter" }
        ],
        "responses": {
          "200": {
            "description": "A page of publicly visible strategies. The array may be empty.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StrategyCollectionEnvelope" },
                "examples": {
                  "page": {
                    "summary": "One strategy on the first page",
                    "value": {
                      "data": [
                        {
                          "id": 4821,
                          "symbol": "BTC",
                          "side": "long",
                          "state": "running",
                          "entry_price": "65000",
                          "target_price": "70000",
                          "stop_price": "62000",
                          "exit_price": null,
                          "target_stages": [
                            {
                              "level": 1,
                              "price": "67000",
                              "reached_at": "2024-01-15T04:00:00+08:00",
                              "reached_price": "67050.5"
                            },
                            {
                              "level": 2,
                              "price": "68500",
                              "reached_at": null,
                              "reached_price": null
                            }
                          ],
                          "note": "Daily breakout; hold while the retest holds.",
                          "source_name": "BTC Trend Tracker",
                          "external_url": "https://example.com/signals/btc-4821",
                          "published_at": "2024-01-15T10:00:00+08:00",
                          "closed_at": null,
                          "updated_at": "2024-01-16T09:30:00+08:00",
                          "circle": {
                            "number": "7000101526",
                            "name": "Crypto Lab",
                            "url": "https://ohmy.xin/circles/7000101526?channel=strategy",
                            "avatar_url": "https://cdn.ohmy.xin/circles/7000101526/avatar.webp"
                          },
                          "author": {
                            "name": "Alice",
                            "avatar_url": "https://cdn.ohmy.xin/users/a1b2c3/avatar.webp"
                          }
                        }
                      ],
                      "meta": {
                        "pagination": {
                          "limit": 20,
                          "has_more": true,
                          "next_cursor": "eyJzIjoidXB1bGlzaGVkX2F0OmRlc2MiLCJjIjpbIjIwMjQtMDEtMTVUMDI6MDA6MDBaIiw0ODIxIl19"
                        },
                        "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidParameter" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/lives": {
      "get": {
        "tags": ["Lives"],
        "summary": "List publicly visible livestreams",
        "description": "Returns the publicly visible livestreams across the platform — scheduled, on air, interrupted, and ended streams.\n\n**Visibility.** A livestream is returned only when all of the following hold:\n\n1. the host has listed it in the circle's livestream directory (`directory_listed`);\n2. its state is `scheduled`, `live`, `interrupted`, or `ended`;\n3. its circle is bound to Mixin, not dormant, and set to public.\n\nUnlike the strategies endpoint, the lives endpoint does **not** require the circle to be free or in teaser mode — lives from paid circles are included.\n\n**Empty results.** When livestreaming is not open to everyone, or the streaming provider is not fully configured, this endpoint returns `200` with an empty array rather than an error.\n\n**Viewer count.** `viewer_count` is populated only while a stream is on air (`live` / `interrupted`); it is `null` in every other state.",
        "operationId": "listLives",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order. The cursor is bound to this value.",
            "schema": {
              "type": "string",
              "enum": ["created_at:desc", "updated_at:desc"],
              "default": "created_at:desc"
            }
          },
          { "$ref": "#/components/parameters/CircleNumber" },
          {
            "name": "state",
            "in": "query",
            "description": "Filter by state, comma-separated.",
            "schema": {
              "type": "string",
              "enum": ["scheduled", "live", "interrupted", "ended"],
              "default": "scheduled,live,interrupted"
            }
          },
          {
            "name": "scheduled_after",
            "in": "query",
            "description": "Lower bound on `scheduled_at` (inclusive). Must be earlier than or equal to `scheduled_before`.",
            "schema": { "type": "string", "format": "date-time" }
          },
          {
            "name": "scheduled_before",
            "in": "query",
            "description": "Upper bound on `scheduled_at` (inclusive). Must be later than or equal to `scheduled_after`.",
            "schema": { "type": "string", "format": "date-time" }
          },
          { "$ref": "#/components/parameters/UpdatedAfter" }
        ],
        "responses": {
          "200": {
            "description": "A page of publicly visible livestreams. The array may be empty.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LiveCollectionEnvelope" },
                "examples": {
                  "page": {
                    "summary": "One livestream on the first page",
                    "value": {
                      "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"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidParameter" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "omx_live_<8-char-id>_<32-char-secret>",
        "description": "An API key generated on the Developer API page. The full secret is shown exactly once, at creation."
      }
    },
    "parameters": {
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "Items per page.",
        "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "The `meta.pagination.next_cursor` from the previous page. Opaque — send it back verbatim. Bound to the `sort` used to produce it.",
        "schema": { "type": "string" }
      },
      "CircleNumber": {
        "name": "circle_number",
        "in": "query",
        "description": "Restrict results to one circle, using the circle's `number`.",
        "schema": { "type": "string", "maxLength": 32 }
      },
      "UpdatedAfter": {
        "name": "updated_after",
        "in": "query",
        "description": "Lower bound on `updated_at` (inclusive).",
        "schema": { "type": "string", "format": "date-time" }
      }
    },
    "responses": {
      "InvalidParameter": {
        "description": "A query parameter is invalid.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "badLimit": {
                "summary": "Out-of-range limit",
                "value": {
                  "error": {
                    "code": "invalid_parameter",
                    "message": "Invalid query parameter: limit must be an integer between 1 and 100.",
                    "details": [
                      { "param": "limit", "reason": "must be an integer between 1 and 100" }
                    ]
                  },
                  "meta": {
                    "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                  }
                }
              },
              "badState": {
                "summary": "Unknown state",
                "value": {
                  "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"
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Credentials missing or malformed, the key is disabled or revoked, or its account is disabled or frozen. The message is identical in every case, by design.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "unauthorized": {
                "summary": "Invalid credentials",
                "value": {
                  "error": {
                    "code": "unauthorized",
                    "message": "Invalid or inactive API credentials."
                  },
                  "meta": {
                    "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                  }
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. The `Retry-After` header says how long to wait.",
        "headers": {
          "Retry-After": {
            "description": "Suggested wait in seconds.",
            "schema": { "type": "integer" }
          },
          "X-RateLimit-Limit": {
            "description": "The account's per-minute request ceiling.",
            "schema": { "type": "integer" }
          },
          "X-RateLimit-Remaining": {
            "description": "Requests left in the current window (0 when throttled).",
            "schema": { "type": "integer" }
          },
          "X-RateLimit-Reset": {
            "description": "Unix epoch seconds when the window resets.",
            "schema": { "type": "integer" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "throttled": {
                "summary": "Throttled",
                "value": {
                  "error": {
                    "code": "rate_limit_exceeded",
                    "message": "Rate limit exceeded. Retry later."
                  },
                  "meta": {
                    "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                  }
                }
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The open API is temporarily switched off platform-wide.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "disabled": {
                "summary": "Service disabled",
                "value": {
                  "error": {
                    "code": "service_unavailable",
                    "message": "External API service is temporarily unavailable."
                  },
                  "meta": {
                    "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                  }
                }
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected server error. Include `meta.request_id` when contacting the platform.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "failed": {
                "summary": "Server error",
                "value": {
                  "error": {
                    "code": "internal_error",
                    "message": "An internal error occurred."
                  },
                  "meta": {
                    "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Unknown endpoint path.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "examples": {
              "missing": {
                "summary": "Unknown path",
                "value": {
                  "error": {
                    "code": "not_found",
                    "message": "API endpoint not found."
                  },
                  "meta": {
                    "request_id": "9f4f2d1e-7c3b-4c68-9f9f-0a1b2c3d4e5f"
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "description": "Metadata attached to every response.",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Unique tracking ID for the request. Also returned in the `X-Request-Id` header — quote it when contacting the platform."
          }
        },
        "required": ["request_id"]
      },
      "Pagination": {
        "type": "object",
        "description": "Cursor pagination state for a collection response.",
        "properties": {
          "limit": {
            "type": "integer",
            "description": "The page size actually applied.",
            "minimum": 1
          },
          "has_more": {
            "type": "boolean",
            "description": "Whether another page exists."
          },
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Cursor for the next page. Null when `has_more` is false. Send it back as the `cursor` query parameter."
          }
        },
        "required": ["limit", "has_more", "next_cursor"]
      },
      "CollectionMeta": {
        "type": "object",
        "properties": {
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "request_id": {
            "type": "string",
            "description": "Unique tracking ID for the request."
          }
        },
        "required": ["pagination", "request_id"]
      },
      "ErrorDetail": {
        "type": "object",
        "description": "One offending query parameter.",
        "properties": {
          "param": {
            "type": "string",
            "description": "The query parameter name."
          },
          "reason": {
            "type": "string",
            "description": "Why the value was rejected."
          }
        },
        "required": ["param", "reason"]
      },
      "ErrorBody": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code.",
            "enum": [
              "invalid_parameter",
              "unauthorized",
              "not_found",
              "rate_limit_exceeded",
              "service_unavailable",
              "internal_error"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation."
          },
          "details": {
            "type": ["array", "null"],
            "description": "Present on `invalid_parameter`: one entry per offending parameter.",
            "items": { "$ref": "#/components/schemas/ErrorDetail" }
          }
        },
        "required": ["code", "message"]
      },
      "ErrorEnvelope": {
        "type": "object",
        "description": "Failure envelope.",
        "properties": {
          "error": { "$ref": "#/components/schemas/ErrorBody" },
          "meta": { "$ref": "#/components/schemas/Meta" }
        },
        "required": ["error", "meta"]
      },
      "Circle": {
        "type": "object",
        "description": "The circle a strategy or livestream belongs to.",
        "properties": {
          "number": {
            "type": "string",
            "description": "Circle number — usable directly as the `circle_number` filter."
          },
          "name": { "type": "string", "description": "Circle name." },
          "url": {
            "type": "string",
            "description": "Circle home page, in the strategy or live channel view.",
            "format": "uri"
          },
          "avatar_url": {
            "type": ["string", "null"],
            "description": "Circle avatar URL.",
            "format": "uri"
          }
        },
        "required": ["number", "name", "url", "avatar_url"]
      },
      "Person": {
        "type": "object",
        "description": "A member or host, reduced to display details. The Mixin UUID is never exposed.",
        "properties": {
          "name": { "type": "string", "description": "Display name." },
          "avatar_url": {
            "type": ["string", "null"],
            "description": "Avatar URL.",
            "format": "uri"
          }
        },
        "required": ["name", "avatar_url"]
      },
      "TargetStage": {
        "type": "object",
        "description": "One level of a strategy's take-profit ladder.",
        "properties": {
          "level": {
            "type": "integer",
            "description": "Position in the ladder, counting from 1.",
            "minimum": 1
          },
          "price": {
            "type": "string",
            "description": "Target price for this level, as a decimal string."
          },
          "reached_at": {
            "type": ["string", "null"],
            "description": "When the level was reached. Null when it has not been.",
            "format": "date-time"
          },
          "reached_price": {
            "type": ["string", "null"],
            "description": "The actual price when the level was reached, as a decimal string. Null when it has not been."
          }
        },
        "required": ["level", "price", "reached_at", "reached_price"]
      },
      "Strategy": {
        "type": "object",
        "description": "A publicly visible trading signal.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The signal's record ID — useful for long-term de-duplication.",
            "readOnly": true
          },
          "symbol": {
            "type": "string",
            "description": "Trading symbol, returned exactly as the author entered it — the platform does not normalize its case. Match it case-insensitively.",
            "examples": ["BTC"]
          },
          "side": {
            "type": "string",
            "enum": ["long", "short"],
            "description": "Direction."
          },
          "state": {
            "type": "string",
            "enum": ["running", "take_profit", "stop_loss"],
            "description": "Signal state."
          },
          "entry_price": {
            "type": "string",
            "description": "Entry price as a decimal string; trailing zeros are stripped."
          },
          "target_price": {
            "type": "string",
            "description": "Target price as a decimal string."
          },
          "stop_price": {
            "type": "string",
            "description": "Stop-loss price as a decimal string."
          },
          "exit_price": {
            "type": ["string", "null"],
            "description": "Actual exit price. Null while the signal is still open."
          },
          "target_stages": {
            "type": "array",
            "description": "The take-profit ladder, one entry per level.",
            "items": { "$ref": "#/components/schemas/TargetStage" }
          },
          "note": {
            "type": ["string", "null"],
            "description": "Note attached by the publisher."
          },
          "source_name": {
            "type": ["string", "null"],
            "description": "Display name of the signal source."
          },
          "external_url": {
            "type": ["string", "null"],
            "description": "Link to the original signal.",
            "format": "uri"
          },
          "published_at": {
            "type": "string",
            "description": "Publish time.",
            "format": "date-time"
          },
          "closed_at": {
            "type": ["string", "null"],
            "description": "Close time. Null while the signal is still running.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "Last update time.",
            "format": "date-time"
          },
          "circle": { "$ref": "#/components/schemas/Circle" },
          "author": {
            "oneOf": [
              { "$ref": "#/components/schemas/Person" },
              { "type": "null" }
            ],
            "description": "The member who published the signal. Null when unavailable."
          }
        },
        "required": [
          "id",
          "symbol",
          "side",
          "state",
          "entry_price",
          "target_price",
          "stop_price",
          "exit_price",
          "target_stages",
          "note",
          "source_name",
          "external_url",
          "published_at",
          "closed_at",
          "updated_at",
          "circle",
          "author"
        ]
      },
      "Live": {
        "type": "object",
        "description": "A publicly visible livestream.",
        "properties": {
          "number": {
            "type": "string",
            "description": "The stream's public number. The internal `id` is never returned."
          },
          "title": { "type": "string", "description": "Stream title." },
          "description": {
            "type": ["string", "null"],
            "description": "Stream description."
          },
          "kind": {
            "type": "string",
            "enum": ["video"],
            "description": "Stream kind."
          },
          "state": {
            "type": "string",
            "enum": ["scheduled", "live", "interrupted", "ended"],
            "description": "Stream state."
          },
          "url": {
            "type": "string",
            "description": "The room URL — share it directly with users.",
            "format": "uri"
          },
          "cover_url": {
            "type": ["string", "null"],
            "description": "Cover image URL.",
            "format": "uri"
          },
          "viewer_count": {
            "type": ["integer", "null"],
            "description": "Current viewers. Populated only while the stream is on air (`live` / `interrupted`); null otherwise.",
            "minimum": 0
          },
          "scheduled_at": {
            "type": ["string", "null"],
            "description": "Scheduled start time.",
            "format": "date-time"
          },
          "started_at": {
            "type": ["string", "null"],
            "description": "Actual start time.",
            "format": "date-time"
          },
          "ended_at": {
            "type": ["string", "null"],
            "description": "End time.",
            "format": "date-time"
          },
          "duration_seconds": {
            "type": "integer",
            "description": "Stream duration in seconds; 0 before it starts or before it ends.",
            "minimum": 0
          },
          "replay_available": {
            "type": "boolean",
            "description": "Whether a replay is available: the stream has ended, the replay is visible, and a recording is ready."
          },
          "comments_count": {
            "type": "integer",
            "description": "Number of comments.",
            "minimum": 0
          },
          "reminders_count": {
            "type": "integer",
            "description": "Number of reminders.",
            "minimum": 0
          },
          "updated_at": {
            "type": "string",
            "description": "Last update time.",
            "format": "date-time"
          },
          "circle": { "$ref": "#/components/schemas/Circle" },
          "host": {
            "oneOf": [
              { "$ref": "#/components/schemas/Person" },
              { "type": "null" }
            ],
            "description": "The host. Null when unavailable."
          }
        },
        "required": [
          "number",
          "title",
          "description",
          "kind",
          "state",
          "url",
          "cover_url",
          "viewer_count",
          "scheduled_at",
          "started_at",
          "ended_at",
          "duration_seconds",
          "replay_available",
          "comments_count",
          "reminders_count",
          "updated_at",
          "circle",
          "host"
        ]
      },
      "HealthEnvelope": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "status": { "type": "string", "const": "ok" },
              "version": { "type": "string", "const": "v1" },
              "timestamp": {
                "type": "string",
                "description": "Server time at the moment of the response.",
                "format": "date-time"
              }
            },
            "required": ["status", "version", "timestamp"]
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        },
        "required": ["data", "meta"]
      },
      "MeEnvelope": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "account": {
                "type": "object",
                "properties": {
                  "number": { "type": "string", "description": "API account number." },
                  "name": { "type": "string", "description": "API account name." },
                  "state": {
                    "type": "string",
                    "enum": ["active", "disabled", "frozen"],
                    "description": "Account state."
                  },
                  "rate_limit_per_minute": {
                    "type": "integer",
                    "description": "The account's effective per-minute request ceiling.",
                    "minimum": 1
                  }
                },
                "required": ["number", "name", "state", "rate_limit_per_minute"]
              },
              "key": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "description": "API key name." },
                  "masked_token": {
                    "type": "string",
                    "description": "The key with its secret masked. The full secret is never returned."
                  },
                  "state": {
                    "type": "string",
                    "enum": ["active", "disabled", "revoked"],
                    "description": "Key state."
                  },
                  "last_used_at": {
                    "type": ["string", "null"],
                    "description": "When the key was last used.",
                    "format": "date-time"
                  }
                },
                "required": ["name", "masked_token", "state", "last_used_at"]
              }
            },
            "required": ["account", "key"]
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        },
        "required": ["data", "meta"]
      },
      "StrategyCollectionEnvelope": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "description": "A page of strategies. May be empty.",
            "items": { "$ref": "#/components/schemas/Strategy" }
          },
          "meta": { "$ref": "#/components/schemas/CollectionMeta" }
        },
        "required": ["data", "meta"]
      },
      "LiveCollectionEnvelope": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "description": "A page of livestreams. May be empty.",
            "items": { "$ref": "#/components/schemas/Live" }
          },
          "meta": { "$ref": "#/components/schemas/CollectionMeta" }
        },
        "required": ["data", "meta"]
      }
    }
  },
  "security": [{ "bearerAuth": [] }]
}
