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

# Send a device a silent test push

> Sends the device a silent push with `pgw_event` `test`, and returns
the push service's answer, so you can check the device's push token.
On iOS the push goes to the remote token as a background push. The
app shows nothing. A test push counts toward
`call_push_rate_per_binding`, and pgw records it as a push event of
type `test`. pgw marks a token dead when the push service reports it
gone, as after a call push.




## OpenAPI

````yaml /reference/openapi.yaml post /bindings/{key}/test-push
openapi: 3.1.0
info:
  title: pgw admin API
  version: 0.4.0
  description: |
    Manage a pgw tenant: its apps, upstreams, managed mode users, bindings,
    and push log.

    The API listens on `admin_listen`, `127.0.0.1:8080` by default, over plain
    HTTP. Every endpoint except `POST /bootstrap`, `POST /tls/reload`, and the
    register bans needs a tenant API key in the `Authorization` header. Those
    need the server's `PGW_BOOTSTRAP_TOKEN`. Request bodies are JSON objects
    of at most 1 MiB, or 16 MiB for `POST /config/sync`, and pgw rejects
    unknown fields. Responses are never cached.

    An unknown path gets `404`, and a method that the path doesn't serve gets
    `405` with an `Allow` header. Every `GET` endpoint also answers `HEAD`.
    An endpoint that needs an API key answers `500` when pgw can't check the
    key.

    The same listener also serves `GET /metrics`, `GET /healthz`, and
    `GET /readyz`, outside `/api/v1` and without authentication. The health
    checks and metrics pages describe them.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: '{baseUrl}'
    description: Your pgw admin listener
    variables:
      baseUrl:
        default: http://127.0.0.1:8080/api/v1
        description: The address of admin_listen, followed by /api/v1.
  - url: http://localhost:8080/api/v1
    description: pgw on this computer
security:
  - apiKey: []
tags:
  - name: Tenant
    description: Create the first tenant and read the caller's tenant.
  - name: Apps
    description: Mobile and web apps and their push credentials.
  - name: Upstreams
    description: PBXs that pgw registers apps with.
  - name: Users
    description: >-
      SIP accounts that pgw checks itself and registers at the PBX in managed
      mode.
  - name: Bindings
    description: Devices registered through pgw.
  - name: Push events
    description: The log of push attempts.
  - name: TLS
    description: The certificate that pgw presents to apps.
  - name: Register bans
    description: >-
      Source addresses that pgw refuses REGISTERs from after too many refused
      credentials.
  - name: Config
    description: Export a tenant's configuration and make it match a snapshot.
paths:
  /bindings/{key}/test-push:
    post:
      tags:
        - Bindings
      summary: Send a device a silent test push
      description: |
        Sends the device a silent push with `pgw_event` `test`, and returns
        the push service's answer, so you can check the device's push token.
        On iOS the push goes to the remote token as a background push. The
        app shows nothing. A test push counts toward
        `call_push_rate_per_binding`, and pgw records it as a push event of
        type `test`. pgw marks a token dead when the push service reports it
        gone, as after a call push.
      operationId: testPush
      parameters:
        - name: key
          in: path
          required: true
          description: The binding's key.
          schema:
            type: string
      responses:
        '200':
          description: The provider's answer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestPushResult'
              examples:
                ok:
                  summary: Apple accepted the push
                  value:
                    result: ok
                    status_code: 200
                    push_type: background
                dead:
                  summary: Apple reported the token gone
                  value:
                    result: dead
                    status_code: 410
                    push_type: background
                    error: 'apns: 410 Unregistered'
                providerError:
                  summary: Google failed the push of an Android device
                  value:
                    result: error
                    status_code: 503
                    push_type: data
                    error: 'fcm: 503'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The tenant has no binding with this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: no such binding
        '409':
          description: |
            The binding has no token that takes a silent push: it registered
            without push parameters, its token is dead, or on iOS it has no
            remote token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  the binding has no push token that takes a silent push: no
                  push parameters, a dead token, or no remote token on iOS
        '429':
          description: The binding reached `call_push_rate_per_binding`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: the binding reached call_push_rate_per_binding
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    TestPushResult:
      type: object
      required:
        - result
        - status_code
      properties:
        result:
          type: string
          enum:
            - ok
            - dead
            - error
          description: '`dead`: the provider reported the token gone, as after an uninstall.'
        status_code:
          type: integer
          description: The provider's HTTP status, or 0 when the push didn't reach it.
        push_type:
          type: string
        error:
          type: string
          description: The provider's error, without the token.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: What went wrong. Never contains the values that you sent.
  responses:
    Unauthorized:
      description: The API key is missing or unknown.
      headers:
        WWW-Authenticate:
          schema:
            type: string
            const: Bearer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: missing or unknown API key
    InternalError:
      description: pgw failed to complete the request. The details are in pgw's log.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal error
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: The tenant API key that `POST /bootstrap` returned.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.