> ## 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 contests ## OpenAPI ````yaml /api-reference/openapi.yaml get /contests 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: /contests: get: tags: - Contests summary: List contests operationId: listContests parameters: - name: status in: query schema: type: string enum: - upcoming - open - pending_reveal - settled - voided - name: round in: query schema: type: string - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' responses: '200': description: Contests content: application/json: schema: allOf: - $ref: '#/components/schemas/ListEnvelope' - type: object properties: data: type: array items: $ref: '#/components/schemas/Contest' '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: 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 Contest: type: object required: - id - title - description - status - start_time - deadline - options - entries_count properties: id: type: string format: uuid title: type: string description: type: - string - 'null' status: type: string enum: - upcoming - open - pending_reveal - settled - voided start_time: type: string format: date-time deadline: type: string format: date-time options: type: array items: $ref: '#/components/schemas/ContestOption' entries_count: type: integer settled_at: type: string format: date-time description: Detail view only, once settled. void_reason: type: string description: Detail view only, when voided. ContestOption: type: object required: - id - title - entries_count - is_correct properties: id: type: string title: type: string entries_count: type: integer is_correct: type: boolean 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' 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). ````