openapi: 3.1.2 info: title: SendPulse Web Push API description: > The SendPulse Web Push API allows you to send browser notifications to your website visitors. It supports subscriber management, advanced segmentation, and detailed tracking of delivery and clicks. version: 1.0.0 x-ai-description: > High-engagement browser notification service. This API enables real-time communication with website subscribers across desktop and mobile browsers, featuring advanced segmentation, scheduled broadcasts, and interactive elements like buttons and custom icons. license: name: Apache 2.0 identifier: Apache-2.0 servers: - url: https://api.sendpulse.com paths: /push/tasks: get: summary: Get a list of sent web push campaigns operationId: getWebPushCampaigns tags: - Campaigns x-ai-role: marketing_automation_specialist x-ai-description: > Retrieves the history of web push broadcasts. Provides a snapshot of campaign status and timing for cross-referencing with website traffic. x-ai-reasoning-instructions: - Use `limit` and `offset` for pagination (max 100 entries per reply). - Apply date filters (`from`, `to`) in `YYYY-MM-DD HH:MM:SS` format. x-ai-responding-instructions: - Summarize the recent web push activity. x-ai-suggestions: - Filter by `website_id` if managing multiple digital properties. x-ai-capabilities: confirmation: type: None parameters: - name: limit in: query schema: type: integer - name: offset in: query schema: type: integer - name: from in: query schema: type: string - name: to in: query schema: type: string - name: website_id in: query schema: type: integer responses: '200': description: List of web push campaigns content: application/json: schema: type: array items: type: object properties: id: type: integer title: type: string body: type: string website_id: type: integer from: type: string to: type: string status: type: integer '401': description: Unauthorized '403': description: Forbidden post: summary: Create a new web push campaign operationId: createWebPushCampaign tags: - Campaigns x-ai-role: web_engagement_specialist x-ai-description: > Triggers a new browser notification broadcast. This endpoint supports rich content (icons, large images) and deep segmentation logic to target specific user cohorts based on language, browser, or custom variables. x-ai-reasoning-instructions: - 'Note the limit: 1 campaign per 15 minutes per website.' - Ensure the `ttl` (lifetime) does not exceed 86400 seconds. - >- If using buttons, ensure the payload is a valid JSON string (max 2 buttons). - Validate that image data is Base64 encoded and under 200KB. x-ai-responding-instructions: - Confirm the campaign has been queued and return the `id`. - Mention any filters applied to the broadcast. x-ai-suggestions: - New_Feature_Alert - Breaking_News_Update x-ai-capabilities: confirmation: type: Required security_info: data_handling: - ResourceStateUpdate requestBody: required: true content: application/json: schema: type: object required: - title - website_id - body - ttl properties: title: type: string website_id: type: integer body: type: string ttl: type: integer maximum: 86400 link: type: string filter_lang: type: string filter_browser: type: string filter_region: type: string description: JSON string of country codes, e.g. ['UK'] filter_url: type: string description: JSON string for URL filtering filter_subscription_date_from: type: string filter_subscription_date_to: type: string filter: type: object description: Segmentation by custom variables stretch_time: type: integer send_date: type: string format: date-time buttons: type: string description: JSON string for buttons image: type: string description: JSON string with name and Base64 data icon: type: string description: JSON string with name and Base64 data responses: '200': description: Campaign created content: application/json: schema: type: object properties: result: type: boolean id: type: integer '401': description: Unauthorized '403': description: Forbidden /push/websites/total: get: summary: Get total number of websites operationId: getWebPushWebsitesTotal tags: - Websites x-ai-role: web_engagement_specialist x-ai-description: > Returns the count of websites currently configured for web push in the account. x-ai-capabilities: confirmation: type: None responses: '200': description: Total count content: application/json: schema: type: object properties: total: type: integer '401': description: Unauthorized '403': description: Forbidden /push/websites: get: summary: Get a list of websites operationId: getWebPushWebsites tags: - Websites x-ai-role: web_engagement_specialist x-ai-description: > Retrieves all websites integrated with the web push service, including their verification status and integration date. x-ai-capabilities: confirmation: type: None parameters: - name: limit in: query schema: type: integer - name: offset in: query schema: type: integer responses: '200': description: List of websites content: application/json: schema: type: array items: type: object properties: id: type: integer url: type: string add_date: type: string status: type: integer '401': description: Unauthorized '403': description: Forbidden /push/websites/{id}/variables: get: summary: Get a list of variables for a website operationId: getWebPushVariables tags: - Websites parameters: [] x-ai-role: marketing_automation_specialist x-ai-description: > Lists all custom data fields (variables) defined for a specific website. These variables are used for advanced segmentation of the subscriber base. x-ai-responding-instructions: - List the available variables and their data types. x-ai-suggestions: - >- Check these variables before constructing a `filter` for a new campaign. x-ai-capabilities: confirmation: type: None responses: '200': description: List of variables content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string type: type: string '401': description: Unauthorized '403': description: Forbidden parameters: - name: id in: path required: true schema: type: integer /push/websites/{id}/subscriptions: get: summary: Get a list of website subscribers operationId: getWebPushSubscriptions tags: - Subscribers parameters: - name: limit in: query schema: type: integer - name: offset in: query schema: type: integer - name: subscription_date_from in: query schema: type: string format: date - name: subscription_date_to in: query schema: type: string format: date x-ai-role: web_engagement_specialist x-ai-description: > Retrieves individual subscriber data including browser, OS, and geographic location. Used for auditing the audience composition. x-ai-reasoning-instructions: - 'Note status codes: 0 (Deactivated), 1 (Active), 6 (Unsubscribed).' x-ai-responding-instructions: - Detail the subscriber demographics for the requested website. x-ai-capabilities: confirmation: type: None responses: '200': description: List of subscribers content: application/json: schema: type: array items: type: object '401': description: Unauthorized '403': description: Forbidden parameters: - name: id in: path required: true schema: type: integer /push/websites/{id}/subscriptions/total: get: summary: Get a total number of website subscribers operationId: getWebPushSubscribersTotal tags: - Subscribers parameters: [] x-ai-role: web_engagement_specialist x-ai-description: > Returns the aggregate subscriber count for a specific website. Used to track audience growth over time. x-ai-capabilities: confirmation: type: None responses: '200': description: Total subscriber count content: application/json: schema: type: object properties: total: type: integer '401': description: Unauthorized '403': description: Forbidden parameters: - name: id in: path required: true schema: type: integer /push/websites/info/{id}: get: summary: Get information about a website operationId: getWebPushWebsiteInfo tags: - Websites parameters: [] x-ai-role: web_engagement_specialist x-ai-description: > Retrieves comprehensive metadata for a website property, including daily subscriber growth and active vs. inactive counts. x-ai-capabilities: confirmation: type: None responses: '200': description: Website information content: application/json: schema: type: object properties: id: type: integer url: type: string status: type: string total_subscribers: type: integer active_subscribers: type: integer '401': description: Unauthorized '403': description: Forbidden parameters: - name: id in: path required: true schema: type: integer /push/websites/{id}/code: get: summary: Get JS code for a website operationId: getWebPushCode tags: - Configuration parameters: [] x-ai-role: web_engagement_specialist x-ai-description: > Retrieves the specific JavaScript snippet required to enable web push functionality on the target website. This script handles the permission prompt and subscriber token generation. x-ai-responding-instructions: - >- Provide the `script_code` and instruct the user to place it before the `` tag. x-ai-capabilities: confirmation: type: None responses: '200': description: Integration code content: application/json: schema: type: object properties: script_url: type: string script_code: type: string '401': description: Unauthorized '403': description: Forbidden parameters: - name: id in: path required: true schema: type: integer /push/subscriptions/state: post: summary: Activate/deactivate a subscriber operationId: setWebPushSubscriberState tags: - Subscribers x-ai-role: web_engagement_specialist x-ai-description: > Manually toggles the active state of a subscriber. Can be used to suppress users or re-activate them based on business logic. x-ai-reasoning-instructions: - 'Set `state: 1` for activation and `0` for deactivation.' x-ai-responding-instructions: - Confirm the subscriber state has been updated. x-ai-capabilities: confirmation: type: Required security_info: data_handling: - ResourceStateUpdate requestBody: required: true content: application/json: schema: type: object required: - id - state properties: id: type: integer state: type: integer enum: - 0 - 1 responses: '200': description: State updated content: application/json: schema: type: object properties: result: type: boolean '401': description: Unauthorized '403': description: Forbidden /push/tasks/{id}: get: summary: Get statistics on sent campaigns operationId: getWebPushCampaignStats tags: - Campaigns parameters: [] x-ai-role: marketing_automation_specialist x-ai-description: > Retrieves final performance metrics for a web push broadcast, including delivered counts and click-through (redirect) rates. x-ai-reasoning-instructions: - >- Analyze the `redirect` vs `delivered` ratio to measure campaign effectiveness. x-ai-responding-instructions: - Report the engagement metrics for the specific campaign. x-ai-capabilities: confirmation: type: None responses: '200': description: Campaign statistics content: application/json: schema: type: object properties: id: type: integer message: type: object website: type: string status: type: integer send: type: string delivered: type: integer redirect: type: integer '401': description: Unauthorized '403': description: Forbidden parameters: - name: id in: path required: true schema: type: integer security: - apiKey: [] - oauth2: [] components: securitySchemes: apiKey: type: http scheme: bearer bearerFormat: API Key description: > Static API Key authentication. A long-lived token generated manually in the SendPulse account settings. x-ai-description: > Permanent authentication token. Ideal for simple integrations without token refresh logic. oauth2: type: oauth2 description: OAuth 2.0 Client Credentials flow for temporary access tokens. flows: clientCredentials: tokenUrl: https://api.sendpulse.com/oauth/access_token scopes: {} x-ai-description: > Standard OAuth 2.0 flow using Client ID and Client Secret. Provides temporary tokens (valid for 1 hour) for enhanced security.