openapi: 3.1.0
info:
  title: APISIX Control API
  description: >-
    APISIX Control API is used to get the internal state of APISIX. In addition
    to the endpoints listed below, certain
    [plugins](/apisix/key-concepts/plugins), such as `server-info`, can add
    additional endpoints to control API.
  version: 3.17.0
tags:
  - name: Schema
    description: >-
      The schema defines the available parameters as well as their data types,
      properties, default values, valid values, and so on.
  - name: Health Check
    description: >-
      Health checking is a mechanism that determines whether upstream services
      are healthy or unhealthy based on their responsiveness.
  - name: Garbage Collection
    description: >-
      Garbage collection is a form of automatic memory management. The garbage
      collector attempts to reclaim memory which was allocated by the program,
      but is no longer referenced.
  - name: Route
    description: |-
      A route defines a path to one or more upstream services.  

      See [Routes](/apisix/key-concepts/routes) for more information.
  - name: Upstream
    description: |-
      An upstream is a logical abstraction of one or more upstream addresses.  

      See [Upstreams](/apisix/key-concepts/upstreams) for more information.
  - name: Service
    description: |-
      A service is a backend application providing a set of functionalities.  

      See [Services](/apisix/key-concepts/services) for more information.
  - name: Plugin Metadata
    description: >-
      Plugin metadata is used to configure the common metadata field(s) of all
      plugin instances sharing the same plugin name.  

      See [Plugin Metadata](/apisix/key-concepts/plugin-metadata) for more
      information.
  - name: Plugin
    description: >-
      Plugins extend base functionalities of APISIX to meet user-specific
      requirements.  
        
      See [Plugins](/apisix/key-concepts/plugins) for more information.
  - name: Service Discovery
    description: >-
      Service discovery is a process used in microservice-based architectures
      for automatically detecting and registering dynamically assigned upstream
      addresses. 


      See [Service
      Discovery](https://docs.api7.ai/apisix/key-concepts/upstreams#service-discovery)
      for more information.
paths:
  /v1/schema:
    get:
      summary: Get JSON Schema
      deprecated: false
      description: Get JSON schema that is used by the APISIX instance.
      tags:
        - Schema
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                '1':
                  summary: Successful Example
                  value:
                    value:
                      main:
                        route:
                          properties: {}
                        upstream:
                          properties: {}
                      plugins:
                        example-plugin:
                          consumer_schema: {}
                          metadata_schema: {}
                          schema: {}
                          type: object
                          priority: 0
                          version: 0.1
                      stream-plugins:
                        mqtt-proxy: {}
        '400':
          description: Schema not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Schema not found.
  /v1/healthcheck:
    get:
      summary: Get Health Check Information
      deprecated: false
      description: >-
        Get health check information of the APISIX instance. You need to
        initiate a request to the route to generate Control API health check
        information.
      tags:
        - Health Check
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    nodes:
                      - ip: 52.86.68.46
                        counter:
                          http_failure: 0
                          success: 0
                          timeout_failure: 0
                          tcp_failure: 0
                        port: 80
                        status: healthy
                      - ip: 100.24.156.8
                        counter:
                          http_failure: 5
                          success: 0
                          timeout_failure: 0
                          tcp_failure: 0
                        port: 80
                        status: unhealthy
                    name: /apisix/routes/1
                    type: http
                '503':
                  description: Failed to get health check count
                  content:
                    application/json:
                      schema:
                        type: object
                        properties:
                          message:
                            type: string
                            example: Failed to get health check count.
  /v1/healthcheck/{src_type}/{src_id}:
    get:
      summary: Get Health Status By Type and ID
      deprecated: false
      description: Get health status of a specified resource.
      tags:
        - Health Check
      parameters:
        - name: src_type
          in: path
          description: The specified resource type.
          required: true
          example: ''
          schema:
            type: string
            enum:
              - routes
              - services
              - upstreams
              - stream_routes
        - name: src_id
          in: path
          description: The specified node ID.
          required: true
          example: ''
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    nodes:
                      - ip: 52.86.68.46
                        counter:
                          http_failure: 0
                          success: 2
                          timeout_failure: 0
                          tcp_failure: 0
                        port: 80
                        status: healthy
                      - ip: 100.24.156.8
                        counter:
                          http_failure: 5
                          success: 0
                          timeout_failure: 0
                          tcp_failure: 0
                        port: 80
                        status: unhealthy
                    type: http
                    name: /apisix/routes/1
        '400':
          description: Invalid src type
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid src type.
        '404':
          description: Missing src ID or src type
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Missing src ID or src type.
  /v1/gc:
    post:
      summary: Trigger Garbage Collection
      deprecated: false
      description: >-
        Trigger a full garbage collection (GC) in the HTTP subsystem. Note that
        a request to this endpoint would not trigger a garbage collection in the
        stream subsystem because the subsystems are run in the separate Lua VM.
      tags:
        - Garbage Collection
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /v1/routes:
    get:
      summary: Get All Routes
      deprecated: false
      description: Get all configured routes.
      tags:
        - Route
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    priority: 0
                    uris:
                      - /hello
                    id: '1'
                    upstream:
                      scheme: http
                      pass_host: pass
                      nodes:
                        - port: 1980
                          host: 127.0.0.1
                          weight: 1
                      type: roundrobin
                      hash_on: vars
                    status: 1
                  clean_handlers: {}
                  has_domain: false
                  orig_modifiedIndex: 1631193445
                  modifiedIndex: 1631193445
                  key: /routes/1
  /v1/routes/{id}:
    get:
      summary: Get Route by ID
      deprecated: false
      description: Get a route by ID.
      tags:
        - Route
      parameters:
        - name: id
          in: path
          description: The specified route ID.
          required: true
          example: ''
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    priority: 0
                    uris:
                      - /hello
                    id: '1'
                    upstream:
                      scheme: http
                      pass_host: pass
                      nodes:
                        - port: 1980
                          host: 127.0.0.1
                          weight: 1
                      type: roundrobin
                      hash_on: vars
                    status: 1
                  clean_handlers: {}
                  has_domain: false
                  orig_modifiedIndex: 1631193445
                  modifiedIndex: 1631193445
                  key: /routes/1
        '404':
          description: Route not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Route not found.
  /v1/services:
    get:
      summary: Get All Services
      deprecated: false
      description: Get all configured services.
      tags:
        - Service
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    has_domain: false
                    clean_handlers: {}
                    modifiedIndex: 671
                    key: /apisix/services/200
                    createdIndex: 671
                    value:
                      upstream:
                        scheme: http
                        hash_on: vars
                        pass_host: pass
                        type: roundrobin
                        nodes:
                          - port: 1980
                            weight: 1
                            host: 127.0.0.1
                      create_time: 1634552648
                      id: '200'
                      plugins:
                        limit-count:
                          key: remote_addr
                          time_window: 60
                          redis_timeout: 1000
                          allow_degradation: false
                          show_limit_quota_header: true
                          policy: local
                          count: 2
                          rejected_code: 503
                      update_time: 1634552648
  /v1/services/{id}:
    get:
      summary: Get Service by ID
      deprecated: false
      description: Get a service by ID.
      tags:
        - Service
      parameters:
        - name: id
          in: path
          description: The pecified service ID.
          required: true
          example: ''
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    has_domain: false
                    clean_handlers: {}
                    modifiedIndex: 728
                    key: /apisix/services/5
                    createdIndex: 728
                    value:
                      create_time: 1634554563
                      id: '5'
                      upstream:
                        scheme: http
                        hash_on: vars
                        pass_host: pass
                        type: roundrobin
                        nodes:
                          - port: 1980
                            weight: 1
                            host: 127.0.0.1
                      update_time: 1634554563
        '404':
          description: Service not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Service not found.
  /v1/upstreams:
    get:
      summary: Get All Upstreams
      deprecated: false
      description: Get all configured upstreams.
      tags:
        - Upstream
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    scheme: http
                    pass_host: pass
                    nodes:
                      - host: 127.0.0.1
                        port: 80
                        weight: 1
                      - host: foo.com
                        port: 80
                        weight: 2
                    hash_on: vars
                    update_time: 1634543819
                    key: remote_addr
                    create_time: 1634539759
                    id: '1'
                    type: chash
                  has_domain: true
                  key: /apisix/upstreams/1
                  clean_handlers: {}
                  createdIndex: 938
                  modifiedIndex: 1225
  /v1/upstreams/{id}:
    get:
      summary: Get Upstream by ID
      deprecated: false
      description: Get an upstream by ID.
      tags:
        - Upstream
      parameters:
        - name: id
          in: path
          description: The specified upstream ID.
          required: true
          example: ''
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    scheme: http
                    pass_host: pass
                    nodes:
                      - host: 127.0.0.1
                        port: 80
                        weight: 1
                      - host: foo.com
                        port: 80
                        weight: 2
                    hash_on: vars
                    update_time: 1634543819
                    key: remote_addr
                    create_time: 1634539759
                    id: '1'
                    type: chash
                  has_domain: true
                  key: /apisix/upstreams/1
                  clean_handlers: {}
                  createdIndex: 938
                  modifiedIndex: 1225
        '404':
          description: Upstream not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Upstream not found.
  /v1/plugin_metadata:
    get:
      summary: Get All Plugin Metadata
      deprecated: false
      description: Get all plugin metadata.
      tags:
        - Plugin Metadata
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    - log_format:
                        upstream_response_time: $upstream_response_time
                      id: file-logger
                    - ikey: 1
                      skey: val
                      id: example-plugin
  /v1/plugin_metadata/{plugin_name}:
    get:
      summary: Get Plugin Metadata by Name
      deprecated: false
      description: Get plugin metadata by the plugin name.
      tags:
        - Plugin Metadata
      parameters:
        - name: plugin_name
          in: path
          description: The specified plugin name.
          required: true
          example: ''
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    log_format:
                      upstream_response_time: $upstream_response_time
                    id: file-logger
        '404':
          description: Plugin metadata not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Plugin not found.
  /v1/plugins/reload:
    put:
      summary: Reload All Plugins
      deprecated: false
      description: >-
        Hot reload plugins for changes to the plugin list in [configuration
        files](/apisix/reference/configuration-files#configyaml-and-configyamlexample)
        or plugin source files to take effect.
      tags:
        - Plugin
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value: done
  /v1/discovery/{service}/dump:
    get:
      summary: Get Memory Dump
      deprecated: false
      description: Get service and configuration details.
      tags:
        - Service Discovery
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    services:
                      svc-a:
                        - host: 192.168.42.145
                          weight: 1
                          port: 9081
                        - host: 192.168.42.145
                          weight: 1
                          port: 9082
                    config:
                      dump:
                        load_on_init: true
                        expire: 2592000
                        path: logs/consul.dump
                      timeout:
                        wait: 60
                        read: 2000
                        connect: 2000
                      fetch_interval: 3
                      keepalive: true
                      weight: 1
                      servers:
                        - http://consul:8500
                      token: ''
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not found.
  /v1/discovery/{service}/show_dump_file:
    get:
      summary: Get Dump File
      deprecated: false
      description: Get configured services details.
      tags:
        - Service Discovery
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                '1':
                  summary: Successful Example
                  value:
                    last_update: 1703594980
                    services:
                      svc-a:
                        - host: 192.168.42.145
                          weight: 1
                          port: 9081
                        - host: 192.168.42.145
                          weight: 1
                          port: 9082
                    expire: 2592000
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not found.
        '503':
          description: Dump file not configured
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: dump params is nil
servers:
  - url: http://127.0.0.1:9090
    description: Dev Environment
components: {}