> ## 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.

# Set App Icon Badge Count

> Shows a number on the ActivitySmith app icon.



## OpenAPI

````yaml POST /badge
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:
  /badge:
    post:
      tags:
        - AppIconBadges
      summary: Set App Icon Badge Count
      description: Shows a number on the ActivitySmith app icon.
      operationId: updateAppIconBadgeCount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppIconBadgeCountUpdateRequest'
            examples:
              set_count:
                value:
                  badge: 8333
              clear_count:
                value:
                  badge: 0
              channel_targeted:
                value:
                  badge: 3
                  target:
                    channels:
                      - sales
                      - customer-success
      responses:
        '200':
          description: App Icon Badge Count updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppIconBadgeCountUpdateResponse'
              examples:
                default:
                  value:
                    success: true
                    badge: 8333
                    devices_notified: 2
                    users_notified: 1
                    effective_channel_slugs: null
                    timestamp: '2026-07-10T12:00:00.000Z'
                channel_targeted:
                  value:
                    success: true
                    badge: 3
                    devices_notified: 2
                    users_notified: 1
                    effective_channel_slugs:
                      - sales
                      - customer-success
                    timestamp: '2026-07-10T12:00:00.000Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: No recipients found for effective channel target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoRecipientsError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
      x-codeSamples:
        - lang: javascript
          label: Node
          source: await activitysmith.badgeCount(8333);
        - lang: python
          label: Python
          source: activitysmith.badge_count(8333)
        - lang: go
          label: Go
          source: activitysmith.BadgeCount(8333)
        - lang: php
          label: PHP
          source: $activitysmith->badgeCount(8333);
        - lang: ruby
          label: Ruby
          source: activitysmith.badge_count(8333)
        - lang: bash
          label: CLI
          source: activitysmith badge 8333
        - lang: bash
          label: cURL
          source: |-
            curl -X POST "https://activitysmith.com/api/badge" \
              -H "Authorization: Bearer $ACTIVITYSMITH_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "badge": 8333
              }'
components:
  schemas:
    AppIconBadgeCountUpdateRequest:
      type: object
      required:
        - badge
      properties:
        badge:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: The count to show on the ActivitySmith app icon. Send 0 to clear it.
        target:
          $ref: '#/components/schemas/ChannelTarget'
      additionalProperties: false
    AppIconBadgeCountUpdateResponse:
      type: object
      properties:
        success:
          type: boolean
        badge:
          type: integer
          minimum: 0
          maximum: 2147483647
        devices_notified:
          type: integer
        users_notified:
          type: integer
        effective_channel_slugs:
          type:
            - array
            - 'null'
          items:
            type: string
        timestamp:
          type: string
          format: date-time
      required:
        - success
        - badge
        - devices_notified
        - users_notified
        - effective_channel_slugs
        - 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
    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
  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.

````