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

# Send Push Notification

> Sends a push notification to devices matched by API key scope and optional target channels. Supports optional redirection URL, optional media preview or playback when the notification is expanded, and up to 4 interactive actions. `media` cannot be combined with `actions`. Optional tags to organize and filter notification history.



## OpenAPI

````yaml POST /push-notification
openapi: 3.1.0
info:
  title: ActivitySmith API
  description: >-
    Send push notifications and Live Activities to your own devices via a single
    API key.
  version: 1.0.0
servers:
  - url: https://activitysmith.com/api
security:
  - apiKeyAuth: []
tags:
  - name: PushNotifications
    description: Send push notifications to paired devices.
  - name: AppIconBadges
    description: Update App Icon Badge Counts on paired devices.
  - name: LiveActivities
    description: Start, update, stream, and end Live Activities.
  - name: Metrics
    description: Update metric values shown in ActivitySmith widgets.
paths:
  /push-notification:
    post:
      tags:
        - PushNotifications
      summary: Send a push notification
      description: >-
        Sends a push notification to devices matched by API key scope and
        optional target channels. Supports optional redirection URL, optional
        media preview or playback when the notification is expanded, and up to 4
        interactive actions. `media` cannot be combined with `actions`. Optional
        tags to organize and filter notification history.
      operationId: sendPushNotification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushNotificationRequest'
            examples:
              default:
                value:
                  title: New subscription 💸
                  message: Customer upgraded to Pro plan
              channel_targeted:
                value:
                  title: New subscription 💸
                  message: Customer upgraded to Pro plan
                  target:
                    channels:
                      - devs
                      - ops
              redirection:
                value:
                  title: Incident Resolved ✅
                  message: All systems operational
                  redirection: https://status.example.com/incidents/abc-123
              media_preview:
                value:
                  title: Homepage ready
                  message: Your agent finished the redesign.
                  media: https://cdn.example.com/output/homepage.png
              media_preview_with_redirection:
                value:
                  title: Homepage ready
                  message: Your agent finished the redesign.
                  media: https://cdn.example.com/output/homepage.png
                  redirection: https://github.com/acme/web/pull/482
              actions_open_url:
                value:
                  title: Release Candidate Ready 🚀
                  message: v2.14.0-rc.1 deployed to staging
                  actions:
                    - title: View CI Run
                      type: open_url
                      url: >-
                        https://github.com/activitysmithhq/backend/actions/runs/1234567890
                    - title: Release Notes
                      type: open_url
                      url: >-
                        https://github.com/activitysmithhq/backend/releases/tag/v2.14.0-rc.1
              actions_webhook:
                value:
                  title: Build Failed 🚨
                  message: Tap and hold for remediation actions
                  redirection: https://ci.example.com/builds/8842
                  actions:
                    - title: Retry Build
                      type: webhook
                      url: https://hooks.example.com/activitysmith/build-retry
                      method: POST
                      body:
                        build_id: '8842'
                        source: push_action
              tagged:
                summary: Organize notification history with tags
                value:
                  title: New subscription 💸
                  message: Customer upgraded to Pro plan
                  tags:
                    - user:382
                    - billing
      responses:
        '200':
          description: Push notification sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushNotificationResponse'
              examples:
                default:
                  value:
                    success: true
                    devices_notified: 2
                    users_notified: 1
                    timestamp: '2025-08-12T12:00:00.000Z'
                channel_targeted:
                  value:
                    success: true
                    devices_notified: 2
                    users_notified: 1
                    effective_channel_slugs:
                      - devs
                      - ops
                    timestamp: '2025-08-12T12:00:00.000Z'
                tagged:
                  value:
                    success: true
                    devices_notified: 2
                    users_notified: 1
                    effective_channel_slugs: null
                    tags:
                      - user:382
                      - billing
                    timestamp: '2025-08-12T12:00:00.000Z'
        '400':
          description: Bad request (invalid payload or channel targeting input)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                invalid_target:
                  value:
                    error: Invalid channel targeting
                    message: target.channels must be an array of channel slugs
                invalid_tags:
                  value:
                    error: Invalid tags
                    code: invalid_tags
                    message: >-
                      tags must use 1-64 lowercase letters, numbers, dashes,
                      underscores, periods, or colons
        '403':
          description: Forbidden (API key scope or channel assignment violation)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
              examples:
                channel_scope_violation:
                  value:
                    error: Invalid channel targeting
                    message: >-
                      This API key can only target assigned channels. Requested
                      channels include channels outside this key scope.
        '404':
          description: No recipients found for effective channel target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoRecipientsError'
              examples:
                no_devices:
                  value:
                    error: No recipients found
                    message: No devices matched the effective channel target
                    effective_channel_slugs:
                      - marketing
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RateLimitError'
                  - $ref: '#/components/schemas/LiveActivityLimitError'
              examples:
                rate_limited:
                  value:
                    error: Rate limit exceeded
                    message: Too many requests, please try again later.
      x-codeSamples:
        - lang: javascript
          label: Node
          source: |-
            import ActivitySmith from "activitysmith";

            const activitysmith = new ActivitySmith({
              apiKey: process.env.ACTIVITYSMITH_API_KEY,
            });

            await activitysmith.notifications.send({
              title: "New subscription 💸",
              message: "Customer upgraded to Pro plan",
            });
        - lang: python
          label: Python
          source: >-
            import os

            from activitysmith import ActivitySmith


            activitysmith =
            ActivitySmith(api_key=os.environ["ACTIVITYSMITH_API_KEY"])


            activitysmith.notifications.send({
                "title": "New subscription 💸",
                "message": "Customer upgraded to Pro plan",
            })
        - lang: go
          label: Go
          source: "package main\n\nimport (\n\t\"log\"\n\n\tactivitysmithsdk \"github.com/ActivitySmithHQ/activitysmith-go\"\n)\n\nfunc main() {\n\tactivitysmith, err := activitysmithsdk.New(\"YOUR-API-KEY\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\t_, err = activitysmith.Notifications.Send(activitysmithsdk.PushNotificationInput{\n\t\tTitle:   \"New subscription 💸\",\n\t\tMessage: \"Customer upgraded to Pro plan\",\n\t})\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n}"
        - lang: php
          label: PHP
          source: |-
            <?php

            use ActivitySmith\ActivitySmith;

            $activitysmith = new ActivitySmith($_ENV['ACTIVITYSMITH_API_KEY']);

            $activitysmith->notifications->send([
                'title' => 'New subscription 💸',
                'message' => 'Customer upgraded to Pro plan',
            ]);
        - lang: ruby
          label: Ruby
          source: >-
            require "activitysmith"


            activitysmith = ActivitySmith::Client.new(api_key:
            ENV.fetch("ACTIVITYSMITH_API_KEY"))


            activitysmith.notifications.send(
              title: "New subscription 💸",
              message: "Customer upgraded to Pro plan"
            )
        - lang: bash
          label: cURL
          source: |-
            curl -X POST "https://activitysmith.com/api/push-notification" \
              -H "Authorization: Bearer $ACTIVITYSMITH_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "title": "New subscription 💸",
                "message": "Customer upgraded to Pro plan"
              }'
components:
  schemas:
    PushNotificationRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        message:
          type: string
        subtitle:
          type: string
        media:
          type: string
          format: uri
          pattern: ^https://
          description: >-
            Optional HTTPS URL for an image, audio file, or video that users can
            preview or play when they expand the notification. If `redirection`
            is omitted, tapping the notification opens this URL. Cannot be
            combined with `actions`.
        redirection:
          type: string
          format: uri
          pattern: ^(http|https|shortcuts)://
          description: >-
            Optional HTTP URL, HTTPS URL, or shortcuts://run-shortcut?name=...
            URL opened when the user taps the notification body. Use
            shortcuts://run-shortcut?name=... to run a specific iPhone Shortcut
            that already exists on the user's device. Overrides the default tap
            target from `media` when both are provided.
        actions:
          type: array
          maxItems: 4
          items:
            $ref: '#/components/schemas/PushNotificationAction'
          description: >-
            Optional interactive actions shown when users expand the
            notification. Cannot be combined with `media`.
        payload:
          type: object
          additionalProperties: true
        badge:
          type: integer
        sound:
          type: string
        target:
          $ref: '#/components/schemas/ChannelTarget'
        tags:
          $ref: '#/components/schemas/TagSlugs'
      additionalProperties: false
    PushNotificationResponse:
      type: object
      properties:
        success:
          type: boolean
        devices_notified:
          type: integer
        users_notified:
          type: integer
        effective_channel_slugs:
          type:
            - array
            - 'null'
          items:
            type: string
        tags:
          $ref: '#/components/schemas/TagSlugs'
        timestamp:
          type: string
          format: date-time
      required:
        - success
        - timestamp
      additionalProperties: false
    BadRequestError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message
      additionalProperties: true
    ForbiddenError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message
      additionalProperties: true
    NoRecipientsError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        effective_channel_slugs:
          type:
            - array
            - 'null'
          items:
            type: string
      required:
        - error
        - message
      additionalProperties: true
    RateLimitError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message
      additionalProperties: false
    LiveActivityLimitError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        limit:
          type: integer
        active:
          type: integer
          description: Current number of active Live Activities.
      required:
        - error
        - message
        - limit
        - active
      additionalProperties: false
    PushNotificationAction:
      type: object
      properties:
        title:
          type: string
          description: Button title displayed in iOS expanded notification UI.
        type:
          $ref: '#/components/schemas/PushNotificationActionType'
        url:
          type: string
          format: uri
          description: >-
            Action URL. For open_url, use an HTTP or HTTPS URL or a
            shortcuts://run-shortcut?name=... URL that runs a specific iPhone
            Shortcut. For webhook, use an HTTPS URL called by the ActivitySmith
            backend.
        method:
          $ref: '#/components/schemas/PushNotificationWebhookMethod'
          description: Webhook HTTP method. Used only when type=webhook.
        body:
          type: object
          additionalProperties: true
          description: Optional webhook payload body. Used only when type=webhook.
      required:
        - title
        - type
        - url
      allOf:
        - if:
            properties:
              type:
                const: open_url
            required:
              - type
          then:
            properties:
              url:
                pattern: ^(http|https|shortcuts)://
        - if:
            properties:
              type:
                const: webhook
            required:
              - type
          then:
            properties:
              url:
                pattern: ^https://
      additionalProperties: false
    ChannelTarget:
      type: object
      properties:
        channels:
          type: array
          items:
            type: string
          minItems: 1
          description: Channel slugs. When omitted, API key scope determines recipients.
      required:
        - channels
      additionalProperties: false
    TagSlugs:
      type: array
      description: Optional tags to organize and filter notification history.
      items:
        type: string
        minLength: 1
        maxLength: 64
        pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
      examples:
        - - user:382
          - environment:production
    PushNotificationActionType:
      type: string
      enum:
        - open_url
        - webhook
    PushNotificationWebhookMethod:
      type: string
      enum:
        - GET
        - POST
      default: POST
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Required. Include `Authorization: Bearer ask_123456789` in every
        request. Replace `ask_123456789` with your API key.

````