> ## Documentation Index > Fetch the complete documentation index at: https://docs.nevua.markets/llms.txt > Use this file to discover all available pages before exploring further. # Create a watchlist subscription > This endpoint creates a subscription that monitors all existing and newly added markets in a watchlist. When 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. ## OpenAPI ````yaml openapi.json post /subscriptions/{watchlistId} openapi: 3.0.0 info: title: Nevua Markets API version: 0.0.1 license: name: ISC url: https://opensource.org/licenses/ISC servers: - url: https://api.nevua.markets description: Production security: [] tags: [] paths: /subscriptions/{watchlistId}: post: tags: - Alerts summary: Create a watchlist subscription description: > This endpoint creates a subscription that monitors all existing and newly added markets in a watchlist. When 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. operationId: createWatchlistSubscription 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 security: - bearerAuth: [] components: schemas: 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 CreateWatchlistScopeSubscriptionJSONResponse: type: object properties: subscriptionId: type: string additionalProperties: false required: - subscriptionId SubscriptionScope.WATCHLIST: type: string enum: - Watchlist 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' 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 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. This 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 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 NotificationChannelType.WEBHOOK: type: string enum: - Webhook SubscriptionType.EVENT_AND_MARKET_OPEN_STATUS_CHANGES: type: string enum: - New or closed events and markets SubscriptionType.CROSSING: type: string enum: - Crossing 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. - For `One Time` rules, this is ignored. - For `Recurring` rules, default is 30 minutes. additionalProperties: false required: - thresholdPercent - triggerType SubscriptionType.CROSSING_UP: type: string enum: - Crossing Up SubscriptionType.CROSSING_DOWN: type: string enum: - Crossing Down SubscriptionType.CROSSING_STEP: type: string enum: - Crossing Step SubscriptionType.GREATER_THAN: type: string enum: - Greater Than SubscriptionType.LESS_THAN: type: string enum: - Less Than TriggerType: type: string enum: - One Time - Recurring TriggerInterval: enum: - 0m - 12h - 24h - 30m - 5m - 60m - 6h type: string securitySchemes: bearerAuth: type: http scheme: bearer ````