openapi: 3.1.0
info:
  title: Apache APISIX Admin Consumer Groups Upstreams API
  description: The Apache APISIX Admin API provides a RESTful interface to dynamically control and configure your deployed Apache APISIX instance. It allows management of routes, services, upstreams, consumers, SSL certificates, global rules, plugin configurations, consumer groups, secrets, and more. By default, the Admin API listens on port 9180 and requires API key authentication via the X-API-KEY header.
  version: 3.14.0
  contact:
    name: Apache APISIX
    url: https://apisix.apache.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: http://127.0.0.1:9180/apisix/admin
  description: Default local Admin API server
security:
- apiKey: []
tags:
- name: Upstreams
  description: Manage upstream backend service definitions with load balancing.
paths:
  /upstreams:
    get:
      operationId: listUpstreams
      summary: Apache APISIX List All Upstreams
      description: Fetches a list of all configured upstreams.
      tags:
      - Upstreams
      responses:
        '200':
          description: Successful response with list of upstreams.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
    post:
      operationId: createUpstream
      summary: Apache APISIX Create an Upstream
      description: Creates a new upstream with a server-generated ID.
      tags:
      - Upstreams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Upstream'
      responses:
        '201':
          description: Upstream created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
  /upstreams/{upstream_id}:
    get:
      operationId: getUpstream
      summary: Apache APISIX Get an Upstream
      description: Fetches the specified upstream by its ID.
      tags:
      - Upstreams
      parameters:
      - $ref: '#/components/parameters/UpstreamId'
      responses:
        '200':
          description: Successful response with upstream details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '404':
          description: Upstream not found.
    put:
      operationId: createOrUpdateUpstream
      summary: Apache APISIX Create or Update an Upstream
      description: Creates an upstream with the specified ID, or updates it if it already exists.
      tags:
      - Upstreams
      parameters:
      - $ref: '#/components/parameters/UpstreamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Upstream'
      responses:
        '200':
          description: Upstream updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '201':
          description: Upstream created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
    patch:
      operationId: patchUpstream
      summary: Apache APISIX Patch an Upstream
      description: Updates partial attributes of the specified upstream.
      tags:
      - Upstreams
      parameters:
      - $ref: '#/components/parameters/UpstreamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Upstream'
      responses:
        '200':
          description: Upstream patched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '404':
          description: Upstream not found.
    delete:
      operationId: deleteUpstream
      summary: Apache APISIX Delete an Upstream
      description: Removes the specified upstream.
      tags:
      - Upstreams
      parameters:
      - $ref: '#/components/parameters/UpstreamId'
      responses:
        '200':
          description: Upstream deleted successfully.
        '404':
          description: Upstream not found.
components:
  schemas:
    ResourceResponse:
      type: object
      description: Standard response wrapper for a single resource.
      properties:
        key:
          type: string
          description: The etcd key path for the resource.
        value:
          type: object
          description: The resource configuration.
        modifiedIndex:
          type: integer
          description: The etcd modification index.
        createdIndex:
          type: integer
          description: The etcd creation index.
    ResourceCreated:
      type: object
      description: Response wrapper for a newly created resource.
      properties:
        key:
          type: string
          description: The etcd key path for the created resource.
        value:
          type: object
          description: The created resource configuration.
    Timeout:
      type: object
      description: Timeout settings for upstream connections.
      properties:
        connect:
          type: number
          default: 60
          description: Connection timeout in seconds.
        send:
          type: number
          default: 60
          description: Send timeout in seconds.
        read:
          type: number
          default: 60
          description: Read timeout in seconds.
    ResourceList:
      type: object
      description: Standard response wrapper for a list of resources.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/ResourceResponse'
          description: Array of resource entries.
        total:
          type: integer
          description: Total count of resources.
    Upstream:
      type: object
      description: An Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to configured rules.
      properties:
        name:
          type: string
          description: Human-readable name for the upstream.
        desc:
          type: string
          description: Description of the upstream.
        type:
          type: string
          enum:
          - roundrobin
          - chash
          - least_conn
          - ewma
          default: roundrobin
          description: Load balancing algorithm.
        nodes:
          oneOf:
          - type: object
            additionalProperties:
              type: integer
            description: Key-value pairs of address:port to weight.
          - type: array
            items:
              type: object
              properties:
                host:
                  type: string
                port:
                  type: integer
                weight:
                  type: integer
                priority:
                  type: integer
                  default: 0
            description: List of node objects.
          description: Backend service nodes.
        service_name:
          type: string
          description: Service name for service discovery.
        discovery_type:
          type: string
          description: Type of service discovery (e.g. dns, consul, nacos, eureka).
        hash_on:
          type: string
          enum:
          - vars
          - header
          - cookie
          - consumer
          - vars_combinations
          default: vars
          description: Hash input for consistent hashing load balancer.
        key:
          type: string
          description: Hash key when using chash load balancer.
        checks:
          type: object
          description: Health check configuration.
          properties:
            active:
              type: object
              description: Active health check configuration.
              properties:
                type:
                  type: string
                  enum:
                  - http
                  - https
                  - tcp
                  default: http
                timeout:
                  type: number
                  default: 1
                http_path:
                  type: string
                  default: /
                host:
                  type: string
                port:
                  type: integer
                https_verify_certificate:
                  type: boolean
                  default: true
                healthy:
                  type: object
                  properties:
                    interval:
                      type: integer
                    successes:
                      type: integer
                unhealthy:
                  type: object
                  properties:
                    interval:
                      type: integer
                    http_failures:
                      type: integer
                    tcp_failures:
                      type: integer
                    timeouts:
                      type: integer
            passive:
              type: object
              description: Passive health check configuration.
              properties:
                type:
                  type: string
                  enum:
                  - http
                  - https
                  - tcp
                  default: http
                healthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                    successes:
                      type: integer
                unhealthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                    http_failures:
                      type: integer
                    tcp_failures:
                      type: integer
                    timeouts:
                      type: integer
        retries:
          type: integer
          description: Number of retries for failed requests.
        retry_timeout:
          type: number
          description: Timeout in seconds for retry requests.
        timeout:
          $ref: '#/components/schemas/Timeout'
        scheme:
          type: string
          enum:
          - http
          - https
          - grpc
          - grpcs
          default: http
          description: The scheme for communicating with the upstream.
        pass_host:
          type: string
          enum:
          - pass
          - node
          - rewrite
          default: pass
          description: How to set the Host header when proxying to upstream.
        upstream_host:
          type: string
          description: Host to use when pass_host is set to rewrite.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs for categorization.
        keepalive_pool:
          type: object
          description: Keepalive pool configuration.
          properties:
            size:
              type: integer
              default: 320
            idle_timeout:
              type: number
              default: 60
            requests:
              type: integer
              default: 1000
        tls:
          type: object
          description: TLS configuration for upstream connections.
          properties:
            client_cert:
              type: string
              description: Client certificate for mTLS.
            client_key:
              type: string
              description: Client private key for mTLS.
  parameters:
    UpstreamId:
      name: upstream_id
      in: path
      required: true
      description: Unique identifier of the upstream.
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Admin API key for authentication.