Disputes.online Disputes API

openapi: 3.2.0
info:
  title: .online public Disputes API
  version: 1.3.0
  summary: Read-only access to prediction disputes and the crowd's stakes on their outcomes.
  description: 'disputes.online is a social prediction platform: people open disputes about real-world events and stake the internal currency (QOT) on outcomes. Payouts are pari-mutuel, so `variant.amount / total_amount` is the crowd''s implied probability of an outcome and `coefficient` is its payout multiplier at the current split.


    No key is required. Lists are cached for about a minute; a few requests per second is plenty. Prose reference: https://disputes.online/llms-full.txt'
  termsOfService: https://disputes.online/info/terms
  contact:
    url: https://disputes.online/info/contacts
servers:
- url: https://disputes.online
tags:
- name: Disputes
paths:
  /disputes/finder:
    get:
      tags:
      - Disputes
      operationId: listDisputes
      summary: List and search disputes
      description: Returns disputes that are still accepting bets.
      parameters:
      - name: q
        in: query
        required: false
        description: Free text, up to 100 characters. A dispute matches when every word occurs in its text or among its tags; matching is case-insensitive and by substring.
        schema:
          type: string
          maxLength: 100
          example: trump impeachment
      - name: lang
        in: query
        required: false
        description: Language code (en, ua, pl, de, …). Returns disputes in that language plus those marked `all`. Defaults to `en`, so send it always.
        schema:
          type: string
          example: en
      - name: moderation
        in: query
        required: false
        description: '`true` returns only disputes that passed moderation. Recommended.'
        schema:
          type: boolean
      - name: categoryid
        in: query
        required: false
        description: One category id.
        schema:
          type: integer
      - name: category_ids
        in: query
        required: false
        description: Several category ids, comma-separated. A parent category does not include its children.
        schema:
          type: string
          example: 201,226
      - name: country
        in: query
        required: false
        description: ISO 3166-1 alpha-2 country the dispute is about.
        schema:
          type: string
          example: US
      - name: city
        in: query
        required: false
        description: City name.
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Statuses to include; repeat the parameter for several. Defaults to all four.
        schema:
          type: array
          items:
            type: string
            enum:
            - new
            - in_process
            - hot
            - very_hot
      - name: min_amount
        in: query
        required: false
        description: Smallest pool size, in QOT.
        schema:
          type: number
          minimum: 0
      - name: max_amount
        in: query
        required: false
        description: Largest pool size, in QOT.
        schema:
          type: number
          minimum: 0
      - name: min_bets_count
        in: query
        required: false
        description: Smallest number of bets.
        schema:
          type: integer
          minimum: 0
      - name: max_bets_count
        in: query
        required: false
        description: Largest number of bets.
        schema:
          type: integer
          minimum: 0
      - name: created_from
        in: query
        required: false
        description: Only disputes created at or after this moment. A full timestamp; a bare date is rejected.
        schema:
          type: string
          format: date-time
          example: '2026-10-07T00:00:00Z'
      - name: created_to
        in: query
        required: false
        description: Only disputes created at or before this moment.
        schema:
          type: string
          format: date-time
          example: '2026-10-07T23:59:59Z'
      - name: sort
        in: query
        required: false
        description: Sort field.
        schema:
          type: string
          enum:
          - amount
          - count_of_bets
          - created_at
          - stop_date
          - finish_date
          default: amount
      - name: sortby
        in: query
        required: false
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: limit
        in: query
        required: false
        description: Page size, at most 20.
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 10
      - name: offset
        in: query
        required: false
        description: Number of items to skip.
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: A page of disputes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeList'
        '422':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /disputes/search:
    get:
      tags:
      - Disputes
      operationId: searchDisputesByTags
      summary: Search disputes by tag
      parameters:
      - name: tags
        in: query
        required: true
        description: One or more lowercase tags, comma-separated.
        schema:
          type: string
          example: politics,usa
      - name: lang
        in: query
        required: false
        description: Language code (en, ua, pl, de, …). Returns disputes in that language plus those marked `all`. Defaults to `en`, so send it always.
        schema:
          type: string
          example: en
      - name: limit
        in: query
        required: false
        description: Page size, at most 20.
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 20
      - name: offset
        in: query
        required: false
        description: Number of items to skip.
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: A page of disputes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeList'
        '422':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: A dispute matches only if it carries every one of the given tags, spelled exactly. Tags are set by the author and many disputes have none; to find disputes about a subject, use `q` on `/disputes/finder` instead.
  /disputes/{id}:
    get:
      tags:
      - Disputes
      operationId: getDispute
      summary: Get one dispute
      parameters:
      - name: id
        in: path
        required: true
        description: Dispute id, as in its page URL https://disputes.online/d/{id}.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The dispute
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Dispute'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /disputes/{id}/odds:
    get:
      tags:
      - Disputes
      operationId: getDisputeOdds
      summary: Get the crowd's current odds on a dispute
      description: 'A compact answer made to be quoted or embedded: the question, its page, the moment of reading, and each outcome''s share of the stakes. Unlike the rest of the API it is cacheable for a minute and readable from any origin (`Access-Control-Allow-Origin: *`).'
      parameters:
      - name: id
        in: path
        required: true
        description: Dispute id.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Current odds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Odds'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /disputes/variant/{id}:
    get:
      tags:
      - Disputes
      operationId: getDisputeByVariant
      summary: Get the dispute an outcome belongs to
      parameters:
      - name: id
        in: path
        required: true
        description: Variant (outcome) id.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The dispute
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Dispute'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Odds:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          description: The dispute's page; link it when citing.
        question:
          type: string
          description: The first line of the dispute's description.
        status:
          type: string
          enum:
          - new
          - in_process
          - hot
          - very_hot
          - ready
          - done
          - dispute
          description: '`new`: no bets yet. `in_process`, `hot`, `very_hot`: accepting bets, by popularity. `ready`: awaiting result. `done`: settled. `dispute`: the result is being contested.'
        as_of:
          type: string
          format: date-time
          description: When these numbers were read. Odds move with every bet.
        closes_at:
          type: string
          format: date-time
          description: When betting closes.
        result_due:
          type: string
          format: date-time
          description: When the result is due.
        total_bets:
          type: integer
        pool_qot:
          type: number
          description: Pool size in QOT, the platform's internal currency — not dollars.
        outcomes:
          type: array
          items:
            $ref: '#/components/schemas/OddsOutcome'
    DisputeList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Dispute'
        total:
          type: integer
          description: Number of disputes matching the filters, across all pages.
    OddsOutcome:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        probability:
          type: number
          minimum: 0
          maximum: 1
          description: Share of all stakes on this outcome.
        payout_multiplier:
          type:
          - number
          - 'null'
          description: What a winning stake is multiplied by at the current split; null when nobody has backed this outcome.
        staked_qot:
          type: number
        bets:
          type: integer
    Dispute:
      type: object
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
          description: The question and its resolution criteria. The first line is the title.
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
        status:
          type: string
          enum:
          - new
          - in_process
          - hot
          - very_hot
          - ready
          - done
          - dispute
          description: '`new`: no bets yet. `in_process`, `hot`, `very_hot`: accepting bets, by popularity. `ready`: awaiting result. `done`: settled. `dispute`: the result is being contested.'
        stop_date:
          type: string
          format: date-time
          description: When betting closes.
        finish_date:
          type: string
          format: date-time
          description: When the result is due.
        uncertain_date:
          type: boolean
          description: True when the event has no fixed date and the dates are estimates.
        total_bets:
          type: integer
          description: Number of bets placed.
        total_amount:
          type: number
          description: Pool size in QOT.
        category_id:
          type: integer
        lang:
          type: string
          description: Language code, or `all`.
        country:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2.
        city:
          type:
          - string
          - 'null'
        tags:
          type: array
          items:
            type: string
        image:
          type:
          - string
          - 'null'
          description: Cover image URL.
        video_url:
          type:
          - string
          - 'null'
        min_bet:
          type:
          - number
          - 'null'
          description: Smallest allowed stake, in QOT.
        max_bet:
          type:
          - number
          - 'null'
          description: Largest allowed stake, in QOT.
        team_id:
          type:
          - string
          - 'null'
          description: Set when the dispute belongs to a team.
        owner:
          type: string
          format: uuid
          description: User who opened the dispute.
        is_local:
          type: boolean
        is_closed:
          type: boolean
        lat:
          type: number
        lng:
          type: number
        radius:
          type: integer
        sport_key:
          type: string
        created_at:
          type: integer
          description: Unix seconds.
        modified_at:
          type: integer
          description: Unix seconds.
    Variant:
      type: object
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
          description: The outcome's text.
        amount:
          type: number
          description: QOT staked on this outcome.
        count_of_bets:
          type: integer
        coefficient:
          type: number
          description: Payout multiplier if this outcome wins, at the current split of stakes.
        image:
          type: string
        probability:
          type: number
          minimum: 0
          maximum: 1
          description: This outcome's share of everything staked on the dispute — the crowd's implied probability. 0 when nobody has bet yet.
    Error:
      type: object
      properties:
        status:
          type: string
        error:
          type: string
externalDocs:
  description: Partner API for creating and settling disputes
  url: https://docs.disputes.online/swagger/index.html