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

# Delete an upstream

> Deletes an upstream that no binding uses. Bindings end when their
registration expires, at most `max_expires` seconds, or the PBX's
minimum when that is longer, after the app last registered. With
`force=true`, pgw deletes the upstream and its bindings together.
pgw can't unregister them at the PBX, so the PBX keeps them until
they expire, and pgw refuses the calls that it sends to them.




## OpenAPI

````yaml /reference/openapi.yaml delete /upstreams/{id}
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:
  /upstreams/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The upstream ID.
        schema:
          type: string
    delete:
      tags:
        - Upstreams
      summary: Delete an upstream
      description: |
        Deletes an upstream that no binding uses. Bindings end when their
        registration expires, at most `max_expires` seconds, or the PBX's
        minimum when that is longer, after the app last registered. With
        `force=true`, pgw deletes the upstream and its bindings together.
        pgw can't unregister them at the PBX, so the PBX keeps them until
        they expire, and pgw refuses the calls that it sends to them.
      operationId: deleteUpstream
      parameters:
        - name: force
          in: query
          required: false
          description: Delete the upstream's bindings with it.
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: The upstream was deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/UpstreamNotFound'
        '409':
          description: Bindings use the upstream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  bindings use this upstream; delete it after they expire, or
                  with force=true
        '500':
          $ref: '#/components/responses/InternalError'
components:
  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
    UpstreamNotFound:
      description: The tenant has no upstream with this ID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: no such upstream
    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
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: What went wrong. Never contains the values that you sent.
  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.