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

# List notifications

> Returns paginated notification history, optionally filtered by status.



## OpenAPI

````yaml /openapi.yaml get /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:
    get:
      tags:
        - Notifications
      summary: List notifications
      description: Returns paginated notification history, optionally filtered by status.
      operationId: listNotifications
      parameters:
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/NotificationStatus'
        - in: query
          name: per_page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: Paginated notification collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
                  links:
                    type: object
                    additionalProperties: true
                  meta:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    NotificationStatus:
      type: string
      enum:
        - queued
        - processing
        - completed
        - partial
        - failed
    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
  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.
    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.

````