openapi.json

{
  "openapi": "3.0.0",
  "servers": [
    {
      "url": "https://api.nevua.markets",
      "description": "Production"
    }
  ],
  "info": {
    "title": "Nevua Markets API",
    "version": "0.0.1",
    "license": {
      "name": "ISC",
      "url": "https://opensource.org/licenses/ISC"
    }
  },
  "components": {
    "schemas": {
      "SearchJSONRequest": {
        "type": "object",
        "properties": {
          "keyphrases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchKeyphrase"
            }
          },
          "searchMatchOperator": {
            "$ref": "#/components/schemas/SearchMatchOperator"
          }
        },
        "additionalProperties": false,
        "required": [
          "keyphrases",
          "searchMatchOperator"
        ]
      },
      "SearchKeyphrase": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "include": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "required": [
          "text"
        ]
      },
      "SearchMatchOperator": {
        "type": "string",
        "enum": [
          "AND",
          "OR"
        ]
      },
      "SearchJSONResponse": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/MatchingEvent"
        }
      },
      "MatchingEvent": {
        "type": "object",
        "properties": {
          "id": {
            "description": "The event ID",
            "type": "string"
          },
          "title": {
            "description": "The event title",
            "type": "string"
          },
          "slug": {
            "description": "The event slug",
            "type": "string"
          },
          "image": {
            "description": "The event image",
            "type": "string"
          },
          "type": {
            "description": "The event type",
            "enum": [
              "event",
              "market"
            ],
            "type": "string"
          },
          "markets": {
            "description": "The markets associated with the event",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "description": "The market ID",
                  "type": "string"
                },
                "image": {
                  "description": "The market image",
                  "type": "string"
                },
                "question": {
                  "description": "The market question",
                  "type": "string"
                },
                "outcomes": {
                  "description": "Outcomes and outcome prices",
                  "type": "string"
                },
                "outcomePrices": {
                  "type": "string"
                },
                "nevuaSVGLink": {
                  "description": "SVG link",
                  "type": "string"
                }
              },
              "additionalProperties": false,
              "required": [
                "id",
                "image",
                "nevuaSVGLink",
                "outcomePrices",
                "outcomes",
                "question"
              ]
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "image",
          "markets",
          "slug",
          "title",
          "type"
        ]
      },
      "SearchTagsJSONRequest": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchTag"
            }
          },
          "searchMatchOperator": {
            "$ref": "#/components/schemas/SearchMatchOperator"
          }
        },
        "additionalProperties": false,
        "required": [
          "searchMatchOperator",
          "tags"
        ]
      },
      "SearchTag": {
        "type": "object",
        "properties": {
          "tagSlug": {
            "type": "string"
          },
          "include": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "required": [
          "tagSlug"
        ]
      },
      "SearchJSONRequestV2": {
        "description": "Search API request body (v2).\nUses the new SearchFilters structure.",
        "type": "object",
        "properties": {
          "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
      },
      "BulkSubscriptionsJSONRequest": {
        "type": "object",
        "properties": {
          "subscriptionIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "subscriptionIds"
        ]
      },
      "GetSubscriptionsJSONResponse": {
        "type": "object",
        "properties": {
          "subscriptions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubscriptionResponse"
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "subscriptions"
        ]
      },
      "SubscriptionResponse": {
        "type": "object",
        "properties": {
          "watchlistId": {
            "type": "string"
          },
          "watchlistName": {
            "type": "string"
          },
          "subscriptionId": {
            "type": "string"
          },
          "eventTitle": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "marketQuestion": {
            "type": "string"
          },
          "marketId": {
            "type": "string"
          },
          "subscriptionScope": {
            "$ref": "#/components/schemas/SubscriptionScope"
          },
          "subscriptionTypeConfig": {
            "$ref": "#/components/schemas/SubscriptionTypeConfig"
          },
          "rule": {
            "$ref": "#/components/schemas/SubscriptionRuleConfig"
          },
          "createdAt": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "$ref": "#/components/schemas/SubscriptionStatus"
          },
          "triggerType": {
            "$ref": "#/components/schemas/TriggerType"
          },
          "triggerInterval": {
            "$ref": "#/components/schemas/TriggerInterval"
          },
          "triggerCount": {
            "type": "number"
          },
          "lastTriggeredAt": {
            "type": "string",
            "nullable": true
          },
          "channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NotificationChannel"
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "channels",
          "createdAt",
          "expiresAt",
          "status",
          "subscriptionId",
          "subscriptionScope",
          "subscriptionTypeConfig",
          "triggerType",
          "watchlistId",
          "watchlistName"
        ]
      },
      "SubscriptionScope": {
        "type": "string",
        "enum": [
          "Watchlist",
          "Event",
          "Market"
        ]
      },
      "SubscriptionTypeConfig": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/CrossingSubscriptionTypeConfig"
          },
          {
            "$ref": "#/components/schemas/CrossingUpSubscriptionTypeConfig"
          },
          {
            "$ref": "#/components/schemas/CrossingDownSubscriptionTypeConfig"
          },
          {
            "$ref": "#/components/schemas/CrossingStepSubscriptionTypeConfig"
          },
          {
            "$ref": "#/components/schemas/GreaterThanSubscriptionTypeConfig"
          },
          {
            "$ref": "#/components/schemas/LessThanSubscriptionTypeConfig"
          },
          {
            "$ref": "#/components/schemas/EventAndMarketOpenStatusChangesSubscriptionTypeConfig"
          }
        ]
      },
      "CrossingSubscriptionTypeConfig": {
        "description": "A 'Crossing' subscription will fire an alert if the price crosses the specified threshold in either direction (up or down).",
        "title": "Crossing",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.CROSSING"
          },
          "config": {
            "$ref": "#/components/schemas/SubscriptionConfig"
          }
        },
        "additionalProperties": false,
        "required": [
          "config",
          "type"
        ]
      },
      "SubscriptionType.CROSSING": {
        "type": "string",
        "enum": [
          "Crossing"
        ]
      },
      "SubscriptionConfig": {
        "type": "object",
        "properties": {
          "params": {
            "$ref": "#/components/schemas/SubscriptionConfig.T"
          }
        },
        "additionalProperties": false,
        "required": [
          "params"
        ]
      },
      "CrossAnyParams": {
        "type": "object",
        "properties": {
          "threshold_percent": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "threshold_percent"
        ]
      },
      "SubscriptionConfig.T": {
        "$ref": "#/components/schemas/CrossAnyParams"
      },
      "CrossingUpSubscriptionTypeConfig": {
        "description": "A 'Crossing Up' subscription will fire an alert if the price crosses the specified threshold upward.",
        "title": "Crossing Up",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.CROSSING_UP"
          },
          "config": {
            "$ref": "#/components/schemas/SubscriptionConfig_1"
          }
        },
        "additionalProperties": false,
        "required": [
          "config",
          "type"
        ]
      },
      "SubscriptionType.CROSSING_UP": {
        "type": "string",
        "enum": [
          "Crossing Up"
        ]
      },
      "SubscriptionConfig_1": {
        "type": "object",
        "properties": {
          "params": {
            "$ref": "#/components/schemas/SubscriptionConfig.T_1"
          }
        },
        "additionalProperties": false,
        "required": [
          "params"
        ]
      },
      "CrossUpParams": {
        "type": "object",
        "properties": {
          "threshold_percent": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "threshold_percent"
        ]
      },
      "SubscriptionConfig.T_1": {
        "$ref": "#/components/schemas/CrossUpParams"
      },
      "CrossingDownSubscriptionTypeConfig": {
        "description": "A 'Crossing Down' subscription will fire an alert if the price crosses the specified threshold downward.",
        "title": "Crossing Down",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.CROSSING_DOWN"
          },
          "config": {
            "$ref": "#/components/schemas/SubscriptionConfig_2"
          }
        },
        "additionalProperties": false,
        "required": [
          "config",
          "type"
        ]
      },
      "SubscriptionType.CROSSING_DOWN": {
        "type": "string",
        "enum": [
          "Crossing Down"
        ]
      },
      "SubscriptionConfig_2": {
        "type": "object",
        "properties": {
          "params": {
            "$ref": "#/components/schemas/SubscriptionConfig.T_2"
          }
        },
        "additionalProperties": false,
        "required": [
          "params"
        ]
      },
      "CrossDownParams": {
        "type": "object",
        "properties": {
          "threshold_percent": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "threshold_percent"
        ]
      },
      "SubscriptionConfig.T_2": {
        "$ref": "#/components/schemas/CrossDownParams"
      },
      "CrossingStepSubscriptionTypeConfig": {
        "description": "A 'Crossing Step' subscription will fire an alert whenever the price crosses set step thresholds. For instance, with a 10% step, you'll get alerts at 10%, 20%, 30%, 40%, and so on, for both up and down movements.",
        "title": "Crossing Step",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.CROSSING_STEP"
          },
          "config": {
            "$ref": "#/components/schemas/SubscriptionConfig_3"
          }
        },
        "additionalProperties": false,
        "required": [
          "config",
          "type"
        ]
      },
      "SubscriptionType.CROSSING_STEP": {
        "type": "string",
        "enum": [
          "Crossing Step"
        ]
      },
      "SubscriptionConfig_3": {
        "type": "object",
        "properties": {
          "params": {
            "$ref": "#/components/schemas/SubscriptionConfig.T_3"
          }
        },
        "additionalProperties": false,
        "required": [
          "params"
        ]
      },
      "CrossStepParams": {
        "type": "object",
        "properties": {
          "threshold_percent": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "threshold_percent"
        ]
      },
      "SubscriptionConfig.T_3": {
        "$ref": "#/components/schemas/CrossStepParams"
      },
      "GreaterThanSubscriptionTypeConfig": {
        "description": "A 'Greater Than' subscription will fire an alert if the price is greater than the specified threshold.",
        "title": "Greater Than",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.GREATER_THAN"
          },
          "config": {
            "$ref": "#/components/schemas/SubscriptionConfig_4"
          }
        },
        "additionalProperties": false,
        "required": [
          "config",
          "type"
        ]
      },
      "SubscriptionType.GREATER_THAN": {
        "type": "string",
        "enum": [
          "Greater Than"
        ]
      },
      "SubscriptionConfig_4": {
        "type": "object",
        "properties": {
          "params": {
            "$ref": "#/components/schemas/SubscriptionConfig.T_4"
          }
        },
        "additionalProperties": false,
        "required": [
          "params"
        ]
      },
      "GreaterThanParams": {
        "type": "object",
        "properties": {
          "threshold_percent": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "threshold_percent"
        ]
      },
      "SubscriptionConfig.T_4": {
        "$ref": "#/components/schemas/GreaterThanParams"
      },
      "LessThanSubscriptionTypeConfig": {
        "description": "A 'Less Than' subscription will fire an alert if the price is less than the specified threshold.",
        "title": "Less Than",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.LESS_THAN"
          },
          "config": {
            "$ref": "#/components/schemas/SubscriptionConfig_5"
          }
        },
        "additionalProperties": false,
        "required": [
          "config",
          "type"
        ]
      },
      "SubscriptionType.LESS_THAN": {
        "type": "string",
        "enum": [
          "Less Than"
        ]
      },
      "SubscriptionConfig_5": {
        "type": "object",
        "properties": {
          "params": {
            "$ref": "#/components/schemas/SubscriptionConfig.T_5"
          }
        },
        "additionalProperties": false,
        "required": [
          "params"
        ]
      },
      "LessThanParams": {
        "type": "object",
        "properties": {
          "threshold_percent": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "threshold_percent"
        ]
      },
      "SubscriptionConfig.T_5": {
        "$ref": "#/components/schemas/LessThanParams"
      },
      "EventAndMarketOpenStatusChangesSubscriptionTypeConfig": {
        "description": "A 'New or closed events and markets' subscription will fire an alert when new events and markets are created or when existing ones close.",
        "title": "Event and Market Status Changes",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.EVENT_AND_MARKET_OPEN_STATUS_CHANGES"
          },
          "config": {
            "$ref": "#/components/schemas/SubscriptionConfig_6"
          }
        },
        "additionalProperties": false,
        "required": [
          "config",
          "type"
        ]
      },
      "SubscriptionType.EVENT_AND_MARKET_OPEN_STATUS_CHANGES": {
        "type": "string",
        "enum": [
          "New or closed events and markets"
        ]
      },
      "SubscriptionConfig_6": {
        "type": "object",
        "properties": {
          "params": {
            "$ref": "#/components/schemas/SubscriptionConfig.T_6"
          }
        },
        "additionalProperties": false,
        "required": [
          "params"
        ]
      },
      "EmptyParams": {
        "type": "object",
        "additionalProperties": false
      },
      "SubscriptionConfig.T_6": {
        "$ref": "#/components/schemas/EmptyParams"
      },
      "SubscriptionRuleConfig": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/EventAndMarketStatusChangesRule"
          },
          {
            "$ref": "#/components/schemas/CrossingRule"
          },
          {
            "$ref": "#/components/schemas/CrossingUpRule"
          },
          {
            "$ref": "#/components/schemas/CrossingDownRule"
          },
          {
            "$ref": "#/components/schemas/CrossingStepRule"
          },
          {
            "$ref": "#/components/schemas/GreaterThanRule"
          },
          {
            "$ref": "#/components/schemas/LessThanRule"
          }
        ]
      },
      "EventAndMarketStatusChangesRule": {
        "description": "A 'New or closed events and markets' rule will fire an alert when new events and markets are created or when existing ones close.\n\nThis rule is always **Recurring** and will fire as soon as a market/event status change is detected.",
        "title": "Event and Market Status Changes",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.EVENT_AND_MARKET_OPEN_STATUS_CHANGES"
          }
        },
        "additionalProperties": false,
        "required": [
          "type"
        ]
      },
      "CrossingRule": {
        "description": "A 'Crossing' rule will fire an alert if the price crosses the specified threshold in either direction (up or down).",
        "title": "Crossing",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.CROSSING"
          },
          "params": {
            "$ref": "#/components/schemas/ThresholdPercentRuleParams"
          }
        },
        "additionalProperties": false,
        "required": [
          "params",
          "type"
        ]
      },
      "ThresholdPercentRuleParams": {
        "type": "object",
        "properties": {
          "thresholdPercent": {
            "type": "number"
          },
          "triggerType": {
            "$ref": "#/components/schemas/TriggerType",
            "description": "Controls if the rule will fire once or repeatedly."
          },
          "triggerInterval": {
            "$ref": "#/components/schemas/TriggerInterval",
            "description": "Controls how often the rule will fire since the last trigger.\n\n- For `One Time` rules, this is ignored.\n- For `Recurring` rules, default is 30 minutes."
          }
        },
        "additionalProperties": false,
        "required": [
          "thresholdPercent",
          "triggerType"
        ]
      },
      "TriggerType": {
        "type": "string",
        "enum": [
          "One Time",
          "Recurring"
        ]
      },
      "TriggerInterval": {
        "enum": [
          "0m",
          "12h",
          "24h",
          "30m",
          "5m",
          "60m",
          "6h"
        ],
        "type": "string"
      },
      "CrossingUpRule": {
        "description": "A 'Crossing Up' rule will fire an alert if the price crosses the specified threshold upward.",
        "title": "Crossing Up",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.CROSSING_UP"
          },
          "params": {
            "$ref": "#/components/schemas/ThresholdPercentRuleParams"
          }
        },
        "additionalProperties": false,
        "required": [
          "params",
          "type"
        ]
      },
      "CrossingDownRule": {
        "description": "A 'Crossing Down' rule will fire an alert if the price crosses the specified threshold downward.",
        "title": "Crossing Down",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.CROSSING_DOWN"
          },
          "params": {
            "$ref": "#/components/schemas/ThresholdPercentRuleParams"
          }
        },
        "additionalProperties": false,
        "required": [
          "params",
          "type"
        ]
      },
      "CrossingStepRule": {
        "description": "A 'Crossing Step' rule will fire an alert whenever the price crosses set step thresholds. For instance, with a 10% step, you'll get alerts at 10%, 20%, 30%, 40%, and so on, for both up and down movements.",
        "title": "Crossing Step",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.CROSSING_STEP"
          },
          "params": {
            "$ref": "#/components/schemas/ThresholdPercentRuleParams"
          }
        },
        "additionalProperties": false,
        "required": [
          "params",
          "type"
        ]
      },
      "GreaterThanRule": {
        "description": "A 'Greater Than' rule will fire an alert if the price is greater than the specified threshold.",
        "title": "Greater Than",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.GREATER_THAN"
          },
          "params": {
            "$ref": "#/components/schemas/ThresholdPercentRuleParams"
          }
        },
        "additionalProperties": false,
        "required": [
          "params",
          "type"
        ]
      },
      "LessThanRule": {
        "description": "A 'Less Than' rule will fire an alert if the price is less than the specified threshold.",
        "title": "Less Than",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SubscriptionType.LESS_THAN"
          },
          "params": {
            "$ref": "#/components/schemas/ThresholdPercentRuleParams"
          }
        },
        "additionalProperties": false,
        "required": [
          "params",
          "type"
        ]
      },
      "SubscriptionStatus": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "reason": {
            "$ref": "#/components/schemas/SubscriptionStatusReason"
          }
        },
        "additionalProperties": false,
        "required": [
          "enabled",
          "reason"
        ]
      },
      "SubscriptionStatusReason": {
        "type": "string",
        "enum": [
          "Created",
          "Updated",
          "Triggered",
          "Paused by user",
          "Restarted by user",
          "Event closed",
          "Market closed"
        ]
      },
      "NotificationChannel": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/NotificationChannelType"
          },
          "settings": {
            "type": "object",
            "properties": {
              "telegramChatId": {
                "type": "number"
              },
              "webhookUrl": {
                "type": "string"
              },
              "discordWebhookUrl": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "status": {
            "enum": [
              "BLOCKED_BY_USER",
              "FAILED",
              "PENDING",
              "READ",
              "SENT"
            ],
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "type"
        ]
      },
      "NotificationChannelType": {
        "type": "string",
        "enum": [
          "In App",
          "Webhook",
          "Discord",
          "Telegram"
        ]
      },
      "CreateWatchlistScopeSubscriptionJSONRequest": {
        "type": "object",
        "properties": {
          "scope": {
            "$ref": "#/components/schemas/SubscriptionScope.WATCHLIST",
            "description": "The scope of the subscription. Currently only `Watchlist` is supported."
          },
          "rule": {
            "$ref": "#/components/schemas/SubscriptionRuleConfig"
          },
          "channels": {
            "description": "The channels to send the alert to.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookNotificationChannel"
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "channels",
          "rule",
          "scope"
        ]
      },
      "SubscriptionScope.WATCHLIST": {
        "type": "string",
        "enum": [
          "Watchlist"
        ]
      },
      "WebhookNotificationChannel": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/NotificationChannelType.WEBHOOK"
          },
          "settings": {
            "type": "object",
            "properties": {
              "webhookUrl": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "webhookUrl"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "settings",
          "type"
        ]
      },
      "NotificationChannelType.WEBHOOK": {
        "type": "string",
        "enum": [
          "Webhook"
        ]
      },
      "CreateWatchlistScopeSubscriptionJSONResponse": {
        "type": "object",
        "properties": {
          "subscriptionId": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "subscriptionId"
        ]
      },
      "CreateWatchListFromTagsJSONRequestV2": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "includeTags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "excludeTags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "matchOperator": {
            "$ref": "#/components/schemas/SearchMatchOperator"
          },
          "automaticallyAddMatchingEvents": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "required": [
          "includeTags",
          "matchOperator",
          "name"
        ]
      },
      "CreateWatchListFromTagsJSONRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchTag"
            }
          },
          "searchMatchOperator": {
            "$ref": "#/components/schemas/SearchMatchOperator"
          },
          "automaticallyAddMatchingEvents": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "searchMatchOperator",
          "tags"
        ]
      },
      "CreateWatchListFromTagsJSONResponse": {
        "type": "object",
        "properties": {
          "watchListId": {
            "type": "string"
          },
          "watchListName": {
            "type": "string"
          },
          "eventCount": {
            "type": "number"
          },
          "marketCount": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "eventCount",
          "marketCount",
          "watchListId",
          "watchListName"
        ]
      },
      "UpdateWatchListTagsJSONRequestV2": {
        "type": "object",
        "properties": {
          "includeTags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "excludeTags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "matchOperator": {
            "$ref": "#/components/schemas/SearchMatchOperator"
          }
        },
        "additionalProperties": false
      },
      "UpdateWatchListTagsJSONRequest": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchTag"
            }
          },
          "searchMatchOperator": {
            "$ref": "#/components/schemas/SearchMatchOperator"
          }
        },
        "additionalProperties": false,
        "required": [
          "tags"
        ]
      },
      "UpdateWatchListTagsJSONResponse": {
        "type": "object",
        "additionalProperties": false
      },
      "DeleteWatchListJSONRequest": {
        "type": "object",
        "properties": {
          "watchListId": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "watchListId"
        ]
      },
      "DeleteWatchListJSONResponse": {
        "type": "object",
        "additionalProperties": false
      },
      "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.\nDuring migration, a query could be in either format."
      },
      "WatchlistQueryV2": {
        "description": "WatchlistQuery using the new SearchFilters structure.\nThis 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"
        ]
      },
      "SearchMatchOperator_1": {
        "type": "string",
        "enum": [
          "AND",
          "OR"
        ]
      },
      "__type": {
        "type": "object",
        "additionalProperties": {
          "type": "object",
          "properties": {
            "autoFetch": {
              "type": "boolean"
            },
            "markets": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false,
          "required": [
            "autoFetch",
            "markets"
          ]
        }
      },
      "EventsMapWithAutoFetch": {
        "$ref": "#/components/schemas/__type"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    }
  },
  "security": [],
  "paths": {
    "/demo/events": {
      "get": {
        "operationId": "demoGetEvents",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Fetch all events",
        "description": "Returns paginated events from the events collection. Default page size is 500.\n",
        "tags": [
          "Demo"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number (1-indexed)"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 500
            },
            "description": "Number of events per page"
          }
        ],
        "responses": {
          "200": {
            "description": "Events retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "active": {
                            "type": "boolean"
                          },
                          "closed": {
                            "type": "boolean"
                          },
                          "volume": {
                            "type": "number"
                          },
                          "startDate": {
                            "type": "string"
                          },
                          "endDate": {
                            "type": "string"
                          },
                          "markets": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    },
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "totalCount": {
                      "type": "integer"
                    },
                    "totalPages": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/demo/webhooks": {
      "post": {
        "operationId": "demoCreateWebhook",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a webhook",
        "description": "Register a webhook URL to receive notifications when events are opened or closed.\n",
        "tags": [
          "Demo"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The webhook URL to send notifications to"
                  }
                }
              },
              "examples": {
                "webhook": {
                  "value": {
                    "url": "https://example.com/webhook"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_id": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "active": {
                      "type": "boolean"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid url"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "get": {
        "operationId": "demoListWebhooks",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List active webhooks",
        "description": "Returns all active demo webhooks.\n",
        "tags": [
          "Demo"
        ],
        "responses": {
          "200": {
            "description": "Active webhooks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhooks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "_id": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "active": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/demo/webhooks/{id}": {
      "delete": {
        "operationId": "demoDeleteWebhook",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a webhook",
        "description": "Soft-deletes a webhook by setting active to false.\n",
        "tags": [
          "Demo"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The webhook document _id"
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid id format"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Webhook not found"
          }
        }
      }
    },
    "/demo/markets/{marketId}/volume-stats": {
      "get": {
        "operationId": "demoGetVolumeStats",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get volume and liquidity stats for a market",
        "description": "Computes volume and liquidity analytics for a specific market from the\nmarket_volume_timeseries collection. Returns volume traded in multiple\ntime windows (1h, 4h, 12h, 24h), volume as a percentage of total,\nliquidity-to-volume ratio, and turnover ratio.\n",
        "tags": [
          "Demo"
        ],
        "parameters": [
          {
            "name": "marketId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The market ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Volume stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "marketId": {
                      "type": "string"
                    },
                    "totalVolume": {
                      "type": "number",
                      "nullable": true,
                      "description": "Latest total cumulative volume (null if missing)"
                    },
                    "latestLiquidity": {
                      "type": "number",
                      "nullable": true,
                      "description": "Most recent liquidity value (null if missing)"
                    },
                    "windows": {
                      "type": "object",
                      "description": "Volume stats per window (1h, 4h, 12h, 24h)",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "volumeTraded": {
                            "type": "number",
                            "nullable": true,
                            "description": "Volume traded in this window (null if volume data missing)"
                          },
                          "volumePercent": {
                            "type": "number",
                            "nullable": true,
                            "description": "volumeTraded / totalVolume (null if totalVolume is 0 or missing)"
                          }
                        }
                      }
                    },
                    "liquidityToVolumeRatio": {
                      "type": "number",
                      "nullable": true,
                      "description": "liquidity / volume_24h"
                    },
                    "turnoverRatio": {
                      "type": "number",
                      "nullable": true,
                      "description": "volume_24h / liquidity"
                    },
                    "datapoints": {
                      "type": "integer",
                      "description": "Number of timeseries datapoints available"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "No data found for this market"
          }
        }
      }
    },
    "/demo/markets/{marketId}/volume-raw": {
      "get": {
        "operationId": "demoGetVolumeRaw",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get raw volume and liquidity timeseries for a market",
        "description": "Returns all raw timeseries data for a specific market, sorted by timestamp ascending.\n",
        "tags": [
          "Demo"
        ],
        "parameters": [
          {
            "name": "marketId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The market ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Raw timeseries data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "marketId": {
                      "type": "string"
                    },
                    "timeseries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "timestamp": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "volumeNum": {
                            "type": "number"
                          },
                          "liquidityNum": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "No data found for this market"
          }
        }
      }
    },
    "/search": {
      "post": {
        "operationId": "searchEvents",
        "summary": "Search by keyphrases",
        "description": "Search for events using keyphrases.\n",
        "tags": [
          "Search"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchJSONRequest"
              },
              "example": {
                "keyphrases": [
                  {
                    "text": "will trump",
                    "include": true
                  }
                ],
                "searchMatchOperator": "OR"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful search response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchJSONResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search/tag-slugs": {
      "post": {
        "operationId": "searchByTagSlugs",
        "summary": "Search by tags",
        "description": "Search for events using tag slugs.\n\nYou can get the full list of tag slugs using the [/tags Polymarket API endpoint](https://docs.polymarket.com/api-reference/tags/list-tags).\n",
        "tags": [
          "Search"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchTagsJSONRequest"
              },
              "example": {
                "tags": [
                  {
                    "text": "sports",
                    "include": true
                  },
                  {
                    "text": "esports",
                    "include": true
                  }
                ],
                "searchMatchOperator": "OR"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful search response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchJSONResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search/v2": {
      "post": {
        "operationId": "searchEventsV2",
        "summary": "Search events (V2)",
        "description": "Search for events using the V2 filter format with explicit include/exclude arrays.\n\nThis endpoint supports searching by both keyphrases and tags in a single request.\nWhen both are provided, results are AND-combined (must match keyphrases AND tags).\n\nThe `matchOperator` controls how terms within each filter type are combined:\n- `OR`: Match any of the include terms\n- `AND`: Match all of the include terms\n\nExclusion terms are always AND-combined (must NOT match any excluded term).\n",
        "tags": [
          "Search"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchJSONRequestV2"
              },
              "examples": {
                "keyphrase_search": {
                  "summary": "Search by keyphrases",
                  "value": {
                    "includeKeyphrases": [
                      "trump",
                      "election"
                    ],
                    "excludeKeyphrases": [
                      "2020"
                    ],
                    "matchOperator": "OR"
                  }
                },
                "tag_search": {
                  "summary": "Search by tags",
                  "value": {
                    "includeTags": [
                      "sports",
                      "esports"
                    ],
                    "matchOperator": "OR"
                  }
                },
                "combined_search": {
                  "summary": "Combined keyphrase and tag search",
                  "value": {
                    "includeKeyphrases": [
                      "championship"
                    ],
                    "includeTags": [
                      "sports"
                    ],
                    "matchOperator": "AND"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful search response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchJSONResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/delete": {
      "post": {
        "operationId": "deleteSubscriptions",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete subscriptions",
        "description": "Delete one or more subscriptions by their IDs. Only subscriptions belonging to the authenticated user can be deleted.\n",
        "tags": [
          "Alerts"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkSubscriptionsJSONRequest"
              },
              "examples": {
                "single_subscription": {
                  "summary": "Delete single subscription",
                  "value": {
                    "subscriptionIds": [
                      "507f191e810c19729de860ea"
                    ]
                  }
                },
                "multiple_subscriptions": {
                  "summary": "Delete multiple subscriptions",
                  "value": {
                    "subscriptionIds": [
                      "507f191e810c19729de860ea",
                      "507f191e810c19729de860eb",
                      "507f191e810c19729de860ec"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscriptions deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "success": {
                    "summary": "Successful deletion",
                    "value": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "no_subscription_ids": {
                    "summary": "No subscription IDs provided",
                    "value": {
                      "error": "No subscription IDs provided"
                    }
                  },
                  "invalid_request_body": {
                    "summary": "Invalid request body format",
                    "value": {
                      "error": "Request body validation failed"
                    }
                  }
                }
              }
            }
          },
          "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/{watchlistId}": {
      "get": {
        "operationId": "getSubscriptions",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get subscriptions",
        "description": "Fetch all subscriptions for the authenticated user. If a watchlistId is provided, only subscriptions for that specific watchlist are returned.\n",
        "tags": [
          "Alerts"
        ],
        "parameters": [
          {
            "name": "watchlistId",
            "in": "path",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional watchlist ID to filter subscriptions. If not provided, returns all user subscriptions."
          }
        ],
        "responses": {
          "200": {
            "description": "Subscriptions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetSubscriptionsJSONResponse"
                },
                "examples": {
                  "all_subscriptions": {
                    "summary": "All user subscriptions",
                    "value": {
                      "subscriptions": [
                        {
                          "subscriptionId": "507f191e810c19729de860ea",
                          "watchlistId": "507f191e810c19729de860eb",
                          "watchlistName": "My Watchlist",
                          "subscriptionScope": "Watchlist",
                          "subscriptionTypeConfig": {
                            "type": "Crossing",
                            "config": {
                              "params": {
                                "threshold_percent": 50
                              }
                            }
                          },
                          "createdAt": "2023-01-01T00:00:00Z",
                          "expiresAt": null,
                          "status": {
                            "enabled": true,
                            "reason": "Created"
                          },
                          "triggerType": "Recurring",
                          "triggerInterval": "30m",
                          "triggerCount": 0,
                          "lastTriggeredAt": null,
                          "channels": [
                            {
                              "type": "Webhook",
                              "settings": {
                                "webhookUrl": "https://example.com/webhook"
                              }
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "watchlist_specific": {
                    "summary": "Subscriptions for specific watchlist",
                    "value": {
                      "subscriptions": [
                        {
                          "subscriptionId": "507f191e810c19729de860ea",
                          "watchlistId": "507f191e810c19729de860eb",
                          "watchlistName": "Trading Signals",
                          "subscriptionScope": "Watchlist",
                          "subscriptionTypeConfig": {
                            "type": "New or closed events and markets",
                            "config": {
                              "params": {}
                            }
                          },
                          "createdAt": "2023-01-01T00:00:00Z",
                          "expiresAt": null,
                          "status": {
                            "enabled": true,
                            "reason": "Created"
                          },
                          "triggerType": "Recurring",
                          "triggerCount": 2,
                          "lastTriggeredAt": "2023-01-01T12:30:00Z",
                          "channels": [
                            {
                              "type": "Webhook",
                              "settings": {
                                "webhookUrl": "https://example.com/status-webhook"
                              }
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "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"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createWatchlistSubscription",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a watchlist subscription",
        "description": "This endpoint creates a subscription that monitors all existing and newly added markets in a watchlist.\n\nWhen the rule condition is met, the subscription will make a POST request to all the configured webhooks. See the [Webhooks](https://docs.nevua.markets//api-reference/alert-webhooks/webhook-payloads) documentation for more details on the webhook payloads.\n",
        "tags": [
          "Alerts"
        ],
        "parameters": [
          {
            "name": "watchlistId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the watchlist to create a subscription for"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWatchlistScopeSubscriptionJSONRequest"
              },
              "examples": {
                "event_status_changes": {
                  "summary": "New or closed events and markets",
                  "value": {
                    "scope": "Watchlist",
                    "rule": {
                      "type": "New or closed events and markets"
                    },
                    "channels": [
                      {
                        "type": "Webhook",
                        "settings": {
                          "webhookUrl": "https://your-webhook-endpoint.com/status-changes"
                        }
                      }
                    ]
                  }
                },
                "crossing_alert": {
                  "summary": "Crossing threshold alert",
                  "value": {
                    "scope": "Watchlist",
                    "rule": {
                      "type": "Crossing",
                      "params": {
                        "threshold_percent": 50,
                        "triggerType": "Recurring",
                        "triggerInterval": "5m"
                      }
                    },
                    "channels": [
                      {
                        "type": "Webhook",
                        "settings": {
                          "webhookUrl": "https://your-webhook-endpoint.com/alerts"
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateWatchlistScopeSubscriptionJSONResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful subscription creation",
                    "value": {
                      "subscriptionId": "507f191e810c19729de860ea"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "no_channels": {
                    "summary": "No notification channels provided",
                    "value": {
                      "error": "No channels found for subscription"
                    }
                  },
                  "watchlist_not_found": {
                    "summary": "Watchlist not found or doesn't belong to user",
                    "value": {
                      "error": "Watchlist not found"
                    }
                  },
                  "duplicate_event_status_subscription": {
                    "summary": "Duplicate event status subscription",
                    "value": {
                      "error": "Only one EVENT_AND_MARKET_OPEN_STATUS_CHANGES subscription is allowed per watchlist"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "user_not_found": {
                    "summary": "User not found",
                    "value": {
                      "error": "User not found"
                    }
                  }
                }
              }
            }
          },
          "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"
                    }
                  }
                },
                "examples": {
                  "creation_failed": {
                    "summary": "Failed to create subscription",
                    "value": {
                      "error": "Failed to create subscription"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/create-from-tags": {
      "post": {
        "operationId": "createWatchlistFromTags",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create live watchlist from tags",
        "description": "This endpoint creates a live watchlist by specifying which tags to monitor:\n\n- When **new** matching events and markets are **created** on Polymarket, they will automatically be added to the watchlist if `automaticallyAddMatchingEvents` is set to true (default).\n- When events and markets are **closed** on Polymarket, they will automatically be removed from the watchlist.\n\nIn order to receive alerts when new events and markets are created or existing ones are closed, [you can create a `New or closed events and markets` subscription for the watchlist](/api-reference/alerts/create-a-subscription).\n\n## Request Formats\n\n### V2 Format (Recommended)\nUses explicit `includeTags`/`excludeTags` arrays:\n```json\n{\n  \"name\": \"Sports & Esports\",\n  \"includeTags\": [\"sports\", \"esports\"],\n  \"excludeTags\": [\"politics\"],\n  \"matchOperator\": \"OR\",\n  \"automaticallyAddMatchingEvents\": true\n}\n```\n\n### V1 Format (Deprecated - will be removed in future version)\nUses `tags` array with `include` boolean:\n```json\n{\n  \"name\": \"Sports & Esports\",\n  \"tags\": [\n    {\"tagSlug\": \"sports\", \"include\": true},\n    {\"tagSlug\": \"esports\", \"include\": true}\n  ],\n  \"searchMatchOperator\": \"OR\"\n}\n```\n",
        "tags": [
          "Watchlists"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/CreateWatchListFromTagsJSONRequestV2"
                  },
                  {
                    "$ref": "#/components/schemas/CreateWatchListFromTagsJSONRequest"
                  }
                ]
              },
              "examples": {
                "v2_sports_watchlist": {
                  "summary": "V2 - Sports watchlist (recommended)",
                  "value": {
                    "name": "Sports & Esports",
                    "includeTags": [
                      "sports",
                      "esports"
                    ],
                    "matchOperator": "OR",
                    "automaticallyAddMatchingEvents": true
                  }
                },
                "v2_crypto_exclude": {
                  "summary": "V2 - Crypto with exclusions",
                  "value": {
                    "name": "Crypto (no memes)",
                    "includeTags": [
                      "crypto"
                    ],
                    "excludeTags": [
                      "meme-coins"
                    ],
                    "matchOperator": "OR"
                  }
                },
                "v1_sports_watchlist": {
                  "summary": "V1 - Sports watchlist (deprecated)",
                  "value": {
                    "name": "Sports & Esports",
                    "tags": [
                      {
                        "tagSlug": "sports",
                        "include": true
                      },
                      {
                        "tagSlug": "esports",
                        "include": true
                      }
                    ],
                    "searchMatchOperator": "OR",
                    "automaticallyAddMatchingEvents": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Watchlist created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateWatchListFromTagsJSONResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful watchlist creation",
                    "value": {
                      "watchListId": "507f1f77bcf86cd799439011",
                      "watchListName": "Sports & Entertainment",
                      "eventCount": 25,
                      "marketCount": 67
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "invalid_name_length": {
                    "summary": "Invalid watchlist name length",
                    "value": {
                      "error": "Watchlist name must be between 1 and 100 characters"
                    }
                  },
                  "empty_name": {
                    "summary": "Empty watchlist name",
                    "value": {
                      "error": "Watchlist name must be between 1 and 100 characters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "user_not_found": {
                    "summary": "User not found",
                    "value": {
                      "error": "User not found and/or invalid API key"
                    }
                  }
                }
              }
            }
          },
          "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/{watchlistId}/query/tags": {
      "patch": {
        "operationId": "updateWatchlistQueryTags",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update watchlist tags query",
        "description": "Replaces the tag-based query of an existing watchlist. This endpoint requires that the watchlist\ncurrently uses tags (not keyphrases) and that at least one valid tag is provided.\n\n## Request Formats\n\n### V2 Format (Recommended)\nUses explicit `includeTags`/`excludeTags` arrays:\n```json\n{\n  \"includeTags\": [\"sports\", \"esports\"],\n  \"excludeTags\": [\"politics\"],\n  \"matchOperator\": \"OR\"\n}\n```\n\n### V1 Format (Deprecated - will be removed in future version)\nUses `tags` array with `include` boolean:\n```json\n{\n  \"tags\": [\n    {\"tagSlug\": \"sports\", \"include\": true}\n  ],\n  \"searchMatchOperator\": \"OR\"\n}\n```\n",
        "tags": [
          "Watchlists"
        ],
        "parameters": [
          {
            "name": "watchlistId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Watchlist identifier.",
            "example": "507f1f77bcf86cd799439011"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/UpdateWatchListTagsJSONRequestV2"
                  },
                  {
                    "$ref": "#/components/schemas/UpdateWatchListTagsJSONRequest"
                  }
                ]
              },
              "examples": {
                "v2_update_tags": {
                  "summary": "V2 - Update tags (recommended)",
                  "value": {
                    "includeTags": [
                      "sports",
                      "esports"
                    ],
                    "matchOperator": "OR"
                  }
                },
                "v2_with_exclusions": {
                  "summary": "V2 - Update with exclusions",
                  "value": {
                    "includeTags": [
                      "crypto"
                    ],
                    "excludeTags": [
                      "meme-coins"
                    ],
                    "matchOperator": "OR"
                  }
                },
                "v1_update_tags_request": {
                  "summary": "V1 - Replace watchlist tags (deprecated)",
                  "value": {
                    "tags": [
                      {
                        "tagSlug": "sports",
                        "include": true
                      },
                      {
                        "tagSlug": "esports",
                        "include": true
                      }
                    ],
                    "searchMatchOperator": "OR"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tags updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateWatchListTagsJSONResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Updated tags",
                    "value": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "empty_tags": {
                    "summary": "Tags list is empty",
                    "value": {
                      "error": "Tags list is empty"
                    }
                  },
                  "mixed_query": {
                    "summary": "Watchlist has keyphrases",
                    "value": {
                      "error": "Watchlists with existing \"keyphrases\" cannot have \"tags\" added. This will be supported in the future."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Watchlist not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "not_found": {
                    "summary": "Watchlist not found",
                    "value": {
                      "error": "Watchlist not found"
                    }
                  }
                }
              }
            }
          },
          "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/delete": {
      "post": {
        "operationId": "deleteWatchlist",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a watchlist",
        "description": "Permanently deletes a watchlist. Any subscriptions created for this watchlist will be cascade-deleted as well.\n\nThis action cannot be undone.\n",
        "tags": [
          "Watchlists"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteWatchListJSONRequest"
              },
              "examples": {
                "delete_request": {
                  "summary": "Delete watchlist request",
                  "value": {
                    "watchListId": "507f1f77bcf86cd799439011"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Watchlist deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteWatchListJSONResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful deletion",
                    "value": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "invalid_request": {
                    "summary": "Invalid request format",
                    "value": {
                      "error": "Invalid request body"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Watchlist not found or doesn't belong to user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "not_found": {
                    "summary": "Watchlist not found",
                    "value": {
                      "error": "Watchlist not found or already deleted"
                    }
                  }
                }
              }
            }
          },
          "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/{watchlistId}": {
      "get": {
        "operationId": "getWatchlists",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get watchlists",
        "description": "Retrieves all watchlists, or a specific one if `watchlistId` is provided. Watchlists are sorted by creation date - newest first.\n",
        "tags": [
          "Watchlists"
        ],
        "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": []
}