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

# Get watchlists

> Retrieves all watchlists, or a specific one if `watchlistId` is provided. Watchlists are sorted by creation date - newest first.




## OpenAPI

````yaml openapi.json get /watchlists/{watchlistId}
openapi: 3.0.0
info:
  title: Nevua Markets API
  version: 0.0.1
  license:
    name: ISC
    url: https://opensource.org/licenses/ISC
servers:
  - url: https://api.nevua.markets
    description: Production
security: []
tags: []
paths:
  /watchlists/{watchlistId}:
    get:
      tags:
        - Watchlists
      summary: Get watchlists
      description: >
        Retrieves all watchlists, or a specific one if `watchlistId` is
        provided. Watchlists are sorted by creation date - newest first.
      operationId: getWatchlists
      parameters:
        - name: watchlistId
          in: path
          required: false
          schema:
            type: string
          description: >-
            Optional watchlist ID. If not provided, returns all user's
            watchlists.
          example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: Successfully retrieved watchlists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWatchListJSONResponse'
              examples:
                all_watchlists:
                  summary: All user watchlists
                  value:
                    watchLists:
                      - id: 507f1f77bcf86cd799439011
                        name: Election Markets
                        query:
                          keyphrases:
                            - text: election
                              include: true
                          tags: []
                          searchMatchOperator: OR
                          createdAt: '2024-09-26T10:30:00.000Z'
                        automaticallyAddMatchingEvents: true
                        events:
                          event123:
                            autoFetch: true
                            markets:
                              - market456
                              - market789
                        createdAt: '2024-09-26T10:30:00.000Z'
                        updatedAt: '2024-09-26T11:00:00.000Z'
                specific_watchlist:
                  summary: Specific watchlist
                  value:
                    watchLists:
                      - id: 507f1f77bcf86cd799439011
                        name: Sports Betting
                        query:
                          keyphrases: []
                          tags:
                            - text: sports
                              include: true
                          searchMatchOperator: AND
                          createdAt: '2024-09-26T10:30:00.000Z'
                        automaticallyAddMatchingEvents: true
                        events: {}
                        createdAt: '2024-09-26T10:30:00.000Z'
        '401':
          description: Unauthorized - invalid or missing authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      security:
        - bearerAuth: []
components:
  schemas:
    GetWatchListJSONResponse:
      type: object
      properties:
        watchLists:
          type: array
          items:
            $ref: '#/components/schemas/WatchListWithId'
      additionalProperties: false
      required:
        - watchLists
    WatchListWithId:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        query:
          $ref: '#/components/schemas/WatchlistQuery'
        automaticallyAddMatchingEvents:
          type: boolean
        events:
          $ref: '#/components/schemas/EventsMapWithAutoFetch'
        hiddenEventIds:
          type: array
          items:
            type: string
        hiddenMarketIds:
          type: array
          items:
            type: string
        createdAt:
          type: string
        updatedAt:
          type: string
      additionalProperties: false
      required:
        - createdAt
        - events
        - id
        - name
    WatchlistQuery:
      anyOf:
        - $ref: '#/components/schemas/WatchlistQueryV2'
        - $ref: '#/components/schemas/WatchlistQueryV1'
      description: |-
        Union type for reading watchlist queries from DB.
        During migration, a query could be in either format.
    EventsMapWithAutoFetch:
      $ref: '#/components/schemas/__type'
    WatchlistQueryV2:
      description: |-
        WatchlistQuery using the new SearchFilters structure.
        This is the target format after migration.
      type: object
      properties:
        createdAt:
          type: string
        includeKeyphrases:
          type: array
          items:
            type: string
          nullable: true
        excludeKeyphrases:
          type: array
          items:
            type: string
          nullable: true
        includeTags:
          type: array
          items:
            type: string
          nullable: true
        excludeTags:
          type: array
          items:
            type: string
          nullable: true
        matchOperator:
          $ref: '#/components/schemas/SearchMatchOperator'
      additionalProperties: false
      required:
        - createdAt
    WatchlistQueryV1:
      type: object
      properties:
        keyphrases:
          type: array
          items:
            $ref: '#/components/schemas/SearchKeyphrase'
          nullable: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/SearchTag'
          nullable: true
        searchMatchOperator:
          $ref: '#/components/schemas/SearchMatchOperator_1'
        createdAt:
          type: string
      additionalProperties: false
      required:
        - createdAt
        - searchMatchOperator
    __type:
      type: object
      additionalProperties:
        type: object
        properties:
          autoFetch:
            type: boolean
          markets:
            type: array
            items:
              type: string
        additionalProperties: false
        required:
          - autoFetch
          - markets
    SearchMatchOperator:
      type: string
      enum:
        - AND
        - OR
    SearchKeyphrase:
      type: object
      properties:
        text:
          type: string
        include:
          type: boolean
      additionalProperties: false
      required:
        - text
    SearchTag:
      type: object
      properties:
        tagSlug:
          type: string
        include:
          type: boolean
      additionalProperties: false
      required:
        - tagSlug
    SearchMatchOperator_1:
      type: string
      enum:
        - AND
        - OR
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````