> ## Documentation Index > Fetch the complete documentation index at: https://docs.seesaw.fun/llms.txt > Use this file to discover all available pages before exploring further. # List top-level comments of a topic > Flat top-level comments (replies stay behind `reply_count`). Comments may include the author's position — useful for sentiment analysis. Poll comments can be vote-gated: then `data` is empty and `gated` is `true`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /topics/{id}/comments openapi: 3.1.0 info: title: SeeSaw Open API version: 1.0.0-beta description: > The **read-only open API** of SeeSaw — a dedicated surface for AI agents and third-party integrations, exposed both as REST (`/open/v1/*`) and as an **MCP server** (`/mcp`, Streamable HTTP, stateless) in the same process. This contract is independent from the app-facing API (`docs/api/swagger.yaml`): it does not inherit app DTO shapes and follows its own conventions. ## Conventions - Field names are `snake_case`; enums are lowercase strings. - Decimals (credits, probabilities, volumes) are **strings**, never floats. - Timestamps are RFC 3339 UTC (`2026-07-04T12:00:00Z`). - The public user identifier is `handle`; every resource carries a human-visitable `url`. - Lists use **opaque cursor pagination**: `{data, next_cursor, has_more}`. `limit` defaults to 20, max 100. Reusing a cursor with different query params does not guarantee continuity. - Single resources are returned bare (no wrapper); errors use `{"error": {"code", "message", "details"}}`. ## Authentication Every request (public data included) requires a **personal API key** (PAT): `Authorization: Bearer sspat_…`. Keys are issued per user (max 5 active), carry `scopes` (currently always `read`), and can be revoked anytime. Key management lives on the app API (`/v1/users/me/api-keys`, JWT auth — see swagger.yaml), NOT on this surface. ## Rate limits (per key) - 120 requests/min and 10,000 requests/day across the surface. - Search is additionally capped at 30 requests/min — a dedicated per-key budget shared by REST `/search` and the MCP `search_topics` tool (search consumes both this window and the general one). - `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` response headers reflect the binding minute window; 429 responses carry `Retry-After`. Over MCP, exceeding a quota surfaces as a tool error naming the retry delay. ## MCP server `POST https://api.seesaw.fun/mcp` (Streamable HTTP, stateless, same `Authorization` header) exposes the same 14 capabilities as tools: `search_topics`, `list_topics`, `get_topic`, `list_topic_comments`, `get_topic_price_history`, `get_user`, `list_user_topics`, `get_leaderboard`, `list_zones`, `get_contest`, `get_my_profile`, `list_my_positions`, `list_my_settlements`, `list_my_topics`. Tool results carry the corresponding REST response JSON. ## Known behavior notes - `status=open` filters by the stored active state: it includes topics past their deadline but not yet settled (the item itself then shows `status: closed`). - `GET /search` with `type=all` returns a fixed-size preview: it ignores `cursor`/`limit` and always reports `has_more: false` with `next_cursor: null`; to paginate, request a single `type`. - The global leaderboard is top-N only (no cursor). servers: - url: https://api.seesaw.fun/open/v1 description: Production security: - apiKey: [] tags: - name: Topics description: Prediction markets and polls (unified "topics") - name: Users description: Public user profiles and their created topics - name: Leaderboards description: Global, zone, and contest leaderboards - name: Zones description: Topic zones (communities) - name: Contests description: World Cup pick'em contests - name: Me description: Data of the authenticated key owner paths: /topics/{id}/comments: get: tags: - Topics summary: List top-level comments of a topic description: | Flat top-level comments (replies stay behind `reply_count`). Comments may include the author's position — useful for sentiment analysis. Poll comments can be vote-gated: then `data` is empty and `gated` is `true`. operationId: listTopicComments parameters: - $ref: '#/components/parameters/TopicID' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' responses: '200': description: Comments, newest first content: application/json: schema: allOf: - $ref: '#/components/schemas/ListEnvelope' - type: object properties: data: type: array items: $ref: '#/components/schemas/Comment' gated: type: boolean description: >- Present and true when the viewer must vote first to see poll comments. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: TopicID: name: id in: path required: true description: Topic UUID (prediction or poll). schema: type: string format: uuid Cursor: name: cursor in: query description: Opaque pagination cursor from a previous response's `next_cursor`. schema: type: string Limit: name: limit in: query description: Page size (max 100). schema: type: integer default: 20 minimum: 1 maximum: 100 schemas: ListEnvelope: type: object description: Uniform list shape. `next_cursor` is null on the last page. required: - data - next_cursor - has_more properties: data: type: array items: {} next_cursor: type: - string - 'null' has_more: type: boolean Comment: type: object required: - id - author - content - created_at - like_count - reply_count - is_creator_comment - author_position properties: id: type: string author: $ref: '#/components/schemas/UserSummary' content: type: string created_at: type: string format: date-time like_count: type: integer reply_count: type: integer is_creator_comment: type: boolean author_position: oneOf: - $ref: '#/components/schemas/AuthorPosition' - type: 'null' UserSummary: type: object description: >- Embedded wherever a user appears. Deliberately carries no financial fields. required: - id - handle - nickname - avatar_url - account_type - url properties: id: type: string format: uuid handle: type: - string - 'null' nickname: type: string avatar_url: type: - string - 'null' account_type: type: string enum: - user - bot url: type: string description: 'Public profile page: https://seesaw.fun/profile/{id}' AuthorPosition: type: object description: The comment author's stake in the topic (sentiment signal). required: - label - option_name properties: label: type: string option_name: type: string Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - INVALID_ARGUMENT - RATE_LIMITED - SERVICE_DISABLED - INTERNAL description: | Stable contract values. `SERVICE_DISABLED` (HTTP 503) is the emergency kill switch; `FORBIDDEN` (HTTP 403) is reserved for future scopes. message: type: string details: type: object description: >- Optional context, e.g. `{"field": "limit"}` or `{"retry_after": 12}`. additionalProperties: true responses: BadRequest: description: Invalid argument (`details.field` names the offending parameter) content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Missing, invalid, revoked, or expired API key (carries `WWW-Authenticate`) headers: WWW-Authenticate: schema: type: string description: Bearer realm="seesaw-open-api" content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- Resource missing, unknown handle, hidden by privacy settings, or removed/hidden by moderation (existence does not leak) content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Rate limit exceeded (see `Retry-After` and `details.retry_after` seconds) headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sspat_ personal API key description: | Personal API key issued per SeeSaw user account: `Authorization: Bearer sspat_…`. Manage keys on the app API (`/v1/users/me/api-keys`). Revocation propagates within ~60 seconds (validation cache window). ````