> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agg.market/llms.txt
> Use this file to discover all available pages before exploring further.

# Find correlated markets by semantic similarity

> Public app-tier Discovery endpoint. Given a natural language query, finds markets whose generated market signals overlap with the query via vector similarity.



## OpenAPI

````yaml /openapi/openapi.json post /correlated-markets/query
openapi: 3.0.2
info:
  title: AGG API
  version: 1.0.0
  description: >-
    Prediction market aggregator REST API — authentication, users, venue events,
    venue markets, orderbooks, charts, and execution workflows.
servers:
  - url: https://api.agg.market
    description: Production
  - url: https://api.staging.agg.market
    description: Staging
security: []
paths:
  /correlated-markets/query:
    post:
      tags:
        - Discovery
      summary: Find correlated markets by semantic similarity
      description: >-
        Public app-tier Discovery endpoint. Given a natural language query,
        finds markets whose generated market signals overlap with the query via
        vector similarity.
      operationId: queryCorrelatedMarkets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  type: string
                limit:
                  type: number
                includeResolved:
                  type: boolean
                direction:
                  type: string
                  enum:
                    - more_likely
                    - less_likely
                balanced:
                  type: boolean
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      required:
                        - venueMarketId
                        - marketQuestion
                        - marketStatus
                        - marketStartDate
                        - marketEndDate
                        - eventTitle
                        - eventStatus
                        - eventStartDate
                        - eventEndDate
                        - score
                        - matchedSignal
                        - matchSource
                        - venue
                      properties:
                        venueMarketId:
                          type: string
                        marketQuestion:
                          type: string
                        marketStatus:
                          type: string
                          enum:
                            - unopened
                            - paused
                            - open
                            - closed
                            - resolved
                        marketStartDate:
                          type: string
                        marketEndDate:
                          type: string
                          nullable: true
                        eventTitle:
                          type: string
                        eventStatus:
                          type: string
                          enum:
                            - unopened
                            - paused
                            - open
                            - closed
                            - resolved
                        eventStartDate:
                          type: string
                        eventEndDate:
                          type: string
                          nullable: true
                        score:
                          type: number
                        matchedSignal:
                          type: object
                          required:
                            - id
                            - text
                            - side
                            - direction
                            - domain
                          properties:
                            id:
                              type: string
                            text:
                              type: string
                            side:
                              type: string
                              enum:
                                - 'yes'
                                - 'no'
                            direction:
                              type: string
                              enum:
                                - more_likely
                                - less_likely
                            domain:
                              type: string
                        matchSource:
                          type: string
                          enum:
                            - signal
                            - title_fallback
                        venue:
                          type: string
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '401':
          description: '401'
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
      security:
        - appId: []
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: x-app-id
      description: Your application ID. Required for all app-tier and user-tier routes.

````