List All Services

GET /apisix/admin/services

List All Services

Retrieve all configured services.

Parameters

• name (query, string, optional): Filter list by name (regex match).
• label (query, string, optional): Filter list to resources with the given label key.
• page (query, integer, optional): Page number (1-based).
• page_size (query, integer, optional): Items per page (10–500). When omitted, no pagination is applied and the full list is returned.

Responses

• 200: Successful response.
• total (integer, required):
• list (array, required):
• list[].key (string, required):
• list[].value (object, required): Service configuration. A service groups an upstream and plugins so multiple routes can share the same backend configuration.
• list[].value.id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
• anyOf variant 1: String ID
• anyOf variant 2: Integer ID
• list[].value.name (string, optional): Human-readable name.
• list[].value.desc (string, optional): Description of this service.
• list[].value.labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
• list[].value.create_time (integer, optional): Unix timestamp of creation. Read-only.
• list[].value.update_time (integer, optional): Unix timestamp of last update. Read-only.
• list[].value.plugins (object, optional): Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.

Example:

{
  "limit-count": {
    "count": 100,
    "time_window": 60
  },
  "key-auth": {}
}

See the Plugin Hub for available plugins and their schemas.

• list[].value.upstream (object, optional): Upstream configuration defining backend service nodes and load balancing behavior.

An upstream must specify either nodes (static list) or service_name + discovery_type (service discovery).

• list[].value.upstream.id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
• anyOf variant 1: String ID
• anyOf variant 2: Integer ID
• list[].value.upstream.name (string, optional): Human-readable name for the upstream.
• list[].value.upstream.desc (string, optional): Description of the upstream.
• list[].value.upstream.labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
• list[].value.upstream.create_time (integer, optional): Unix timestamp when the upstream was created. Read-only, set automatically.
• list[].value.upstream.update_time (integer, optional): Unix timestamp when the upstream was last updated. Read-only, set automatically.
• list[].value.upstream.nodes (object, optional): The upstream endpoints.
• allOf variant 1
• anyOf variant 1: Weight Mapping
• anyOf variant 2: Node Objects
• list[].value.upstream.nodes[].host (string, required): Hostname or IP address of the upstream node.
• list[].value.upstream.nodes[].port (integer, optional): Port of the upstream node.
• list[].value.upstream.nodes[].weight (integer, required): Weight for load balancing. Higher values mean more traffic. 0 means no traffic.
• list[].value.upstream.nodes[].priority (integer, optional): Priority of the node. Nodes with higher priority are used first. Lower-priority nodes serve as fallbacks.
• list[].value.upstream.nodes[].metadata (object, optional): Arbitrary metadata associated with this node.
• list[].value.upstream.retries (integer, optional): Number of retry attempts when a request to the upstream fails.
• list[].value.upstream.retry_timeout (number, optional): Maximum time in seconds for retry attempts. 0 disables the retry timeout.
• list[].value.upstream.timeout (object, optional): Timeout settings in seconds for connecting to, sending data to, and reading data from the upstream.
• list[].value.upstream.timeout.connect (number, required): Timeout in seconds for establishing a connection to the upstream.
• list[].value.upstream.timeout.send (number, required): Timeout in seconds for sending data to the upstream.
• list[].value.upstream.timeout.read (number, required): Timeout in seconds for reading the response from the upstream.
• list[].value.upstream.type (string, optional): Load balancing algorithm.
• list[].value.upstream.hash_on (string, optional): What to hash on when type is chash.
• list[].value.upstream.key (string, optional): The hash key used when type is chash. Required when hash_on is header, cookie, vars, or vars_combinations. Not needed when hash_on is consumer.
• list[].value.upstream.scheme (string, optional): Protocol for communicating with upstream nodes.
• list[].value.upstream.checks (object, optional): Health check configuration for monitoring upstream node availability. Active checks require at least the active field.
• list[].value.upstream.checks.active (object, optional): Active health check configuration. APISIX periodically sends probes to upstream nodes to determine their health status.
• list[].value.upstream.checks.active.type (string, optional): Protocol type for health check probes.
• list[].value.upstream.checks.active.timeout (number, optional): Timeout in seconds for each health check probe.
• list[].value.upstream.checks.active.concurrency (integer, optional): Number of targets to check concurrently during active health checks.
• list[].value.upstream.checks.active.host (string, optional): Hostname to use in the health check probe Host header. Defaults to the upstream node's host.
• list[].value.upstream.checks.active.port (integer, optional): Port to use for health check probes. Defaults to the upstream node's port.
• list[].value.upstream.checks.active.http_path (string, optional): HTTP request path for health check probes.
• list[].value.upstream.checks.active.https_verify_certificate (boolean, optional): Whether to verify the upstream's TLS certificate during HTTPS health checks.
• list[].value.upstream.checks.active.req_headers (array, optional): Additional HTTP headers to include in health check probe requests.
• list[].value.upstream.checks.active.healthy (object, optional): Thresholds for considering a target healthy during active checks.
• list[].value.upstream.checks.active.healthy.interval (integer, optional): Interval in seconds between active health check probes for healthy targets.
• list[].value.upstream.checks.active.healthy.http_statuses (array, optional): HTTP status codes that indicate a healthy target.
• list[].value.upstream.checks.active.healthy.successes (integer, optional): Number of consecutive successful probes to consider a target healthy.
• list[].value.upstream.checks.active.unhealthy (object, optional): Thresholds for considering a target unhealthy during active checks.
• list[].value.upstream.checks.active.unhealthy.interval (integer, optional): Interval in seconds between active health check probes for unhealthy targets.
• list[].value.upstream.checks.active.unhealthy.http_statuses (array, optional): HTTP status codes that indicate an unhealthy target.
• list[].value.upstream.checks.active.unhealthy.http_failures (integer, optional): Number of HTTP failures to consider a target unhealthy.
• list[].value.upstream.checks.active.unhealthy.tcp_failures (integer, optional): Number of TCP connection failures to consider a target unhealthy.
• list[].value.upstream.checks.active.unhealthy.timeouts (integer, optional): Number of probe timeouts to consider a target unhealthy.
• list[].value.upstream.checks.passive (object, optional): Passive health check configuration. APISIX monitors real traffic responses to determine upstream node health — no extra probes are sent.
• list[].value.upstream.checks.passive.type (string, optional): Protocol type for passive health monitoring.
• list[].value.upstream.checks.passive.healthy (object, optional): Thresholds for considering a target healthy based on real traffic responses.
• list[].value.upstream.checks.passive.healthy.http_statuses (array, optional): HTTP status codes from real traffic that indicate a healthy target.
• list[].value.upstream.checks.passive.healthy.successes (integer, optional): Number of consecutive successful requests to restore a target to healthy status.
• list[].value.upstream.checks.passive.unhealthy (object, optional): Thresholds for considering a target unhealthy based on real traffic responses.
• list[].value.upstream.checks.passive.unhealthy.http_statuses (array, optional): HTTP status codes from real traffic that indicate an unhealthy target.
• list[].value.upstream.checks.passive.unhealthy.tcp_failures (integer, optional): Number of TCP failures from real traffic to consider a target unhealthy.
• list[].value.upstream.checks.passive.unhealthy.timeouts (integer, optional): Number of timeouts from real traffic to consider a target unhealthy.
• list[].value.upstream.checks.passive.unhealthy.http_failures (integer, optional): Number of HTTP failures from real traffic to consider a target unhealthy.
• anyOf variant 1: Active Check
• anyOf variant 2: Passive Check
• list[].value.upstream.tls (object, optional): TLS configuration for connecting to upstream nodes over HTTPS/gRPCS.
• list[].value.upstream.tls.client_cert_id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
• anyOf variant 1: String ID
• anyOf variant 2: Integer ID
• list[].value.upstream.tls.client_cert (string, optional): PEM-encoded client certificate for mTLS with the upstream.
• list[].value.upstream.tls.client_key (string, optional): PEM-encoded client private key for mTLS with the upstream.
• list[].value.upstream.tls.verify (boolean, optional): Whether to verify the upstream server's TLS certificate. Currently only supported for Kafka upstreams.
• list[].value.upstream.keepalive_pool (object, optional): Connection pool configuration for keepalive connections to upstream nodes.
• list[].value.upstream.keepalive_pool.size (integer, optional): Maximum number of keepalive connections cached in the connection pool.
• list[].value.upstream.keepalive_pool.idle_timeout (number, optional): Time in seconds after which an idle keepalive connection is closed. 0 disables the timeout.
• list[].value.upstream.keepalive_pool.requests (integer, optional): Maximum number of requests that can be sent over a single keepalive connection before it is closed.
• list[].value.upstream.pass_host (string, optional): How to set the Host header when proxying to the upstream.
• list[].value.upstream.upstream_host (string, optional): Custom Host header value. Only effective when pass_host is rewrite.
• list[].value.upstream.discovery_type (string, optional): Service discovery type (e.g., dns, consul, nacos, eureka). Required when using service discovery instead of static nodes.
• list[].value.upstream.discovery_args (object, optional): Additional arguments for service discovery.
• list[].value.upstream.discovery_args.namespace_id (string, optional): Namespace ID for Nacos service discovery.
• list[].value.upstream.discovery_args.group_name (string, optional): Group name for service discovery.
• list[].value.upstream.service_name (string, optional): Service name for service discovery. Required when discovery_type is set.
• oneOf variant 1: Use Upstream Nodes
• oneOf variant 2: Use Service Registry
• list[].value.upstream_id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
• anyOf variant 1: String ID
• anyOf variant 2: Integer ID
• list[].value.script (string, optional): Lua script for plugin orchestration.
• list[].value.enable_websocket (boolean, optional): Enable WebSocket proxying for routes using this service.
• list[].value.hosts (array, optional): Hostnames associated with this service.
• list[].createdIndex (integer, optional):
• list[].modifiedIndex (integer, optional):
• 401: Unauthorized — The API key is missing, invalid, or lacks permission.
• error_msg (string, required): Authentication error message.
• description (string, optional): Detailed reason for the authentication failure.

cURL

curl -X GET 'http://127.0.0.1:9180/apisix/admin/services'