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

# List registered devices

> Lists the tenant's live bindings in key order, one page at a time.
pgw never returns push tokens. To get the next page, pass the
response's `next` as `after`.




## OpenAPI

````yaml /reference/openapi.yaml get /bindings
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:
    get:
      tags:
        - Bindings
      summary: List registered devices
      description: |
        Lists the tenant's live bindings in key order, one page at a time.
        pgw never returns push tokens. To get the next page, pass the
        response's `next` as `after`.
      operationId: listBindings
      parameters:
        - name: limit
          in: query
          required: false
          description: The number of bindings to return.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: after
          in: query
          required: false
          description: >-
            Return the bindings whose key comes after this one. Pass the
            previous page's `next`.
          schema:
            type: string
      responses:
        '200':
          description: One page of the tenant's bindings.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                  - next
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Binding'
                  next:
                    type: string
                    description: The `after` of the next page, or empty on the last page.
              example:
                items:
                  - key: Bk2mR7xQ4tLw9NvP1yZc5g
                    app_id: Hf2kP9wQ7mXc3LrN8vBd5g
                    upstream_id: Ux9cT4mK7pLw2RvN5yQs8g
                    aor: sip:alice@pbx.example.com
                    contact_uri: sip:alice@192.0.2.44:51234;transport=tls
                    platform: ios
                    provider: apns
                    sandbox: false
                    transport: TLS
                    remote_addr: 192.0.2.44:51234
                    user_agent: Example Phone 3.2.1 (iOS 18.1)
                    app_expires: '2026-11-23T09:30:00Z'
                    upstream_expires: '2026-11-16T10:30:00Z'
                    last_register_at: '2026-11-16T09:30:00Z'
                    flow_alive: true
                  - key: Mg6vN3pQ8wLr1XkT5zBc2A
                    app_id: Tz6rJ1nY4sKb9WqE2uMc7A
                    upstream_id: Ux9cT4mK7pLw2RvN5yQs8g
                    aor: sip:bob@pbx.example.com
                    contact_uri: sip:bob@[2001:db8::7]:40112;transport=tls
                    platform: android
                    provider: fcm
                    sandbox: false
                    transport: TLS
                    remote_addr: '[2001:db8::7]:40112'
                    app_expires: '2026-11-23T08:02:10Z'
                    upstream_expires: '2026-11-16T09:02:10Z'
                    last_register_at: '2026-11-16T08:02:10Z'
                    flow_alive: false
                next: Mg6vN3pQ8wLr1XkT5zBc2A
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Binding:
      type: object
      required:
        - key
        - app_id
        - upstream_id
        - aor
        - contact_uri
        - platform
        - provider
        - sandbox
        - transport
        - remote_addr
        - app_expires
        - upstream_expires
        - last_register_at
        - flow_alive
      properties:
        key:
          type: string
          description: The binding's flow token.
        app_id:
          type: string
        upstream_id:
          type: string
        aor:
          type: string
          description: >-
            The device's SIP address of record, such as
            `sip:alice@pbx.example.com`.
        contact_uri:
          type: string
          description: The device's Contact URI, without push parameters.
        platform:
          type: string
        provider:
          type: string
          description: The push provider from the device's `pn-provider`.
        sandbox:
          type: boolean
          description: Whether the device uses the APNs sandbox.
        transport:
          type: string
        remote_addr:
          type: string
          description: The address that the device connected from.
        user_agent:
          type: string
          maxLength: 128
          description: >-
            The User-Agent header of the device's last REGISTER, without control
            characters and cut to 128 bytes. Log lines show it as `device`.
            Absent when the device sent none.
        app_expires:
          type: string
          format: date-time
          description: When the device's registration with pgw expires.
        upstream_expires:
          type: string
          format: date-time
          description: When the registration at the PBX expires.
        last_register_at:
          type: string
          format: date-time
        dead_reason:
          type: string
          description: >-
            Present when the push service reported the push token as invalid and
            pgw couldn't delete the binding.
        flow_alive:
          type: boolean
          description: |
            Whether the device's connection to pgw was open when pgw answered.
            pgw delivers calls over an open connection without a push.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: What went wrong. Never contains the values that you sent.
  responses:
    BadRequest:
      description: >-
        The request body or a parameter isn't valid. The message names the
        field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            field:
              summary: A field that isn't valid
              value:
                error: 'invalid request: platform must be "ios", "android", or "web"'
            json:
              summary: A body that isn't valid JSON
              value:
                error: 'invalid JSON body: unknown field "colour"'
            limit:
              summary: A query parameter out of range
              value:
                error: limit must be from 1 to 1000
    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.