Update a Service (Partial)

PATCH /apisix/admin/services/{id}

Update a Service (Partial)

Partially update a service's configuration.

Parameters

• id (path, string, required): Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.
• ttl (query, integer, optional): Time-to-live in seconds. The resource is automatically removed when it expires.

Request body

Fields to merge into the existing Service. Object fields are merged recursively; arrays are replaced.

Content type: application/json

• 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
• anyOf variant 3
• name (string,null, optional): Human-readable name.
• desc (string,null, optional): Description of this service.
• labels (object,null, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
• create_time (integer,null, optional): Unix timestamp of creation. Read-only.
• update_time (integer,null, optional): Unix timestamp of last update. Read-only.
• plugins (object,null, 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.

• upstream (object,null, 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).

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

Responses

• 200: Successful response.
• key (string, required):
• value (object, required): Service configuration. A service groups an upstream and plugins so multiple routes can share the same backend configuration.
• 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
• value.name (string, optional): Human-readable name.
• value.desc (string, optional): Description of this service.
• value.labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
• value.create_time (integer, optional): Unix timestamp of creation. Read-only.
• value.update_time (integer, optional): Unix timestamp of last update. Read-only.
• 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.

• 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).

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

cURL

curl -X PATCH 'http://127.0.0.1:9180/apisix/admin/services/{id}'