> ## 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. # Browse topics by ranking > Lists prediction markets or polls (the two kinds are separate lists, no mixed ranking). Filters: - `sort=ending_soon` is prediction-only (400 for polls). - `status` defaults to `open`. `resolving` is not filterable (omit `status` instead); polls only support `open`. - `zone` is prediction-only (400 for polls). ## OpenAPI ````yaml /api-reference/openapi.yaml get /topics 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: get: tags: - Topics summary: Browse topics by ranking description: | Lists prediction markets or polls (the two kinds are separate lists, no mixed ranking). Filters: - `sort=ending_soon` is prediction-only (400 for polls). - `status` defaults to `open`. `resolving` is not filterable (omit `status` instead); polls only support `open`. - `zone` is prediction-only (400 for polls). operationId: listTopics parameters: - name: type in: query schema: type: string enum: - prediction - poll default: prediction - name: sort in: query schema: type: string enum: - trending - newest - ending_soon default: trending - name: status in: query schema: type: string enum: - open - closed - resolved - refunded default: open - name: zone in: query description: Zone slug (prediction-only) schema: type: string - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' responses: '200': description: Topics ordered by the requested ranking content: application/json: schema: $ref: '#/components/schemas/TopicList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' components: parameters: 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: TopicList: allOf: - $ref: '#/components/schemas/ListEnvelope' - type: object properties: data: type: array items: $ref: '#/components/schemas/TopicSummary' 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 TopicSummary: type: object description: | Unified prediction+poll card for lists and search. Deliberately trimmed (no description/images) — fetch the topic for details. `total_volume`/`traders_count` are prediction-only; `voters_count`/`total_stake`/`votes_visible` are poll-only. required: - id - type - title - status - created_at - end_time - comments_count - favorites_count - url - options properties: id: type: string format: uuid type: type: string enum: - prediction - poll title: type: string status: type: string enum: - open - closed - resolving - resolved - refunded description: | Unified lifecycle. `closed` = past deadline, not yet settled; `resolving` = outcome being determined (prediction only). creator: $ref: '#/components/schemas/UserSummary' created_at: type: string format: date-time end_time: type: - string - 'null' format: date-time comments_count: type: integer favorites_count: type: integer url: type: string description: >- Share page: https://seesaw.fun/topic/{id} (prediction) or /poll/{id} (poll). options: type: array items: $ref: '#/components/schemas/TopicOption' total_volume: type: string description: Prediction-only. Decimal string. traders_count: type: integer description: Prediction-only. voters_count: type: integer description: Poll-only. total_stake: type: string description: Poll-only. Decimal string. votes_visible: type: boolean description: >- Poll-only. False until the viewer voted or the poll settled; option `votes_count` is null then. moderation_status: type: string description: Owner view only — populated exclusively by `GET /me/topics`. 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 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}' TopicOption: description: Shape depends on the parent topic's `type`. oneOf: - $ref: '#/components/schemas/PredictionOption' - $ref: '#/components/schemas/PollOption' PredictionOption: type: object required: - id - name - probability - is_winner properties: id: type: string name: type: string probability: type: string description: Current probability as a decimal string (0–1). is_winner: type: boolean PollOption: type: object required: - id - name - votes_count - is_winner properties: id: type: string name: type: string votes_count: type: - integer - 'null' description: >- Null (not 0) while the distribution is gated (`votes_visible=false`). is_winner: type: boolean 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' 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). ````