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

# Send a notification

> Queues a notification for eligible installations belonging to the specified external users.



## OpenAPI

````yaml /openapi.yaml post /api/v1/notifications
openapi: 3.0.3
info:
  title: Pushctl API
  version: 1.0.0
  description: >-
    Application-scoped APIs for registering installations, sending push
    notifications, and tracking delivery events.
  license:
    name: Proprietary
servers:
  - url: https://pushctl.com
security:
  - bearerAuth: []
tags:
  - name: Installations
    description: Register and maintain mobile app installations.
  - name: Notifications
    description: Create notifications and inspect their delivery lifecycle.
  - name: Delivery events
    description: Report lifecycle events emitted by a client installation.
paths:
  /api/v1/notifications:
    post:
      tags:
        - Notifications
      summary: Send a notification
      description: >-
        Queues a notification for eligible installations belonging to the
        specified external users.
      operationId: sendANotification
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          description: >-
            Stable key for safely retrying one logical send. Maximum 255
            characters.
          schema:
            type: string
            maxLength: 255
          example: order-ready:01K2EXAMPLE:v1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationRequest'
      responses:
        '202':
          description: Notification accepted for asynchronous fanout.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/NotificationResponse'
                  - type: object
                    properties:
                      meta:
                        type: object
                        properties:
                          accepted:
                            type: boolean
                            example: true
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    NotificationRequest:
      type: object
      required:
        - recipients
        - notification
      properties:
        recipients:
          type: object
          required:
            - user_ids
          properties:
            user_ids:
              type: array
              minItems: 1
              maxItems: 500
              uniqueItems: true
              items:
                type: string
                maxLength: 255
              example:
                - user-123
                - user-456
        notification:
          type: object
          description: Provide a title, body, or non-empty data object.
          properties:
            title:
              type: string
              maxLength: 255
              nullable: true
              example: Order ready
            body:
              type: string
              maxLength: 4096
              nullable: true
              example: Your order is ready for collection.
            image_url:
              type: string
              format: uri
              maxLength: 2048
              nullable: true
            action_url:
              type: string
              maxLength: 2048
              nullable: true
              example: myapp://orders/123
        data:
          type: object
          additionalProperties: true
          example:
            order_id: 123
        options:
          type: object
          properties:
            ttl:
              type: integer
              minimum: 0
              maximum: 2419200
            priority:
              type: string
              enum:
                - normal
                - high
            collapse_id:
              type: string
              maxLength: 64
            sound:
              type: string
              maxLength: 255
            badge:
              type: integer
              minimum: 0
            android_channel_id:
              type: string
              maxLength: 255
            ios_category:
              type: string
              maxLength: 255
            platform_overrides:
              type: object
              properties:
                ios:
                  type: object
                  additionalProperties: true
                android:
                  type: object
                  additionalProperties: true
    NotificationResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Notification'
    Notification:
      type: object
      required:
        - id
        - status
        - notification
        - data
        - options
        - target_users
        - statistics
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/NotificationStatus'
        notification:
          type: object
          properties:
            title:
              type: string
              nullable: true
            body:
              type: string
              nullable: true
            image_url:
              type: string
              nullable: true
            action_url:
              type: string
              nullable: true
        data:
          type: object
          additionalProperties: true
        options:
          type: object
          additionalProperties: true
        target_users:
          type: integer
        statistics:
          type: object
          properties:
            users:
              type: integer
            installations:
              type: integer
            accepted:
              type: integer
            received:
              type: integer
            displayed:
              type: integer
            opened:
              type: integer
            failed:
              type: integer
            skipped:
              type: integer
        created_at:
          type: string
          format: date-time
          nullable: true
        processing_started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
    NotificationStatus:
      type: string
      enum:
        - queued
        - processing
        - completed
        - partial
        - failed
  responses:
    Unauthenticated:
      description: Token is missing, invalid, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Unauthenticated.
    Forbidden:
      description: The token lacks the required ability.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: This action is unauthorized.
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
    RateLimited:
      description: Per-application rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: application token
      description: >-
        Use an application-scoped token with the ability required by the
        endpoint.

````