---
title: "Creates or Updates MeshTimeout entity"
method: PUT
path: "/v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshtimeouts/{name}"
tags: ["MeshTimeout"]
---

# Creates or Updates MeshTimeout entity

`PUT /v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshtimeouts/{name}`

## Request

- Base URL: `https://global.api.konghq.com`
- URL: `https://global.api.konghq.com/v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshtimeouts/{name}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

## Path parameters

- `mesh` string, required
- `name` string, required

## Request body

- MeshTimeoutItem: MeshTimeout configures timeout limits for service-to-service communication to prevent requests from hanging indefinitely. It supports connection timeouts, idle timeouts, and HTTP-specific timeouts (request, stream, headers) to ensure timely failure detection and improve service responsiveness.
  - `type` 'MeshTimeout', required: the type of the resource
  - `mesh` string: Mesh is the name of the Kuma mesh this resource belongs to. It may be omitted for cluster-scoped resources.
  - `kri` string: A unique identifier for this resource instance used by internal tooling and integrations. Typically derived from resource attributes and may be used for cross-references or indexing
  - `name` string, required: Name of the Kuma resource
  - `labels` object: The labels to help identity resources
  - `spec` object, required: Spec is the specification of the Kuma MeshTimeout resource.
    - `from` object[]: From list makes a match between clients and corresponding configurations
      - `default` object: Default is a configuration specific to the group of clients referenced in 'targetRef'
        - `connectionTimeout` string: ConnectionTimeout specifies the amount of time proxy will wait for an TCP connection to be established. Default value is 5 seconds. Cannot be set to 0.
        - `http` object: Http provides configuration for HTTP specific timeouts
          - `maxConnectionDuration` string: MaxConnectionDuration is the time after which a connection will be drained and/or closed, starting from when it was first established. Setting this timeout to 0 will disable it. Disabled by default.
          - `maxStreamDuration` string: MaxStreamDuration is the maximum time that a stream’s lifetime will span. Setting this timeout to 0 will disable it. Disabled by default.
          - `requestHeadersTimeout` string: RequestHeadersTimeout The amount of time that proxy will wait for the request headers to be received. The timer is activated when the first byte of the headers is received, and is disarmed when the last byte of the headers has been received. If not specified or set to 0, this timeout is disabled. Disabled by default.
          - `requestTimeout` string: RequestTimeout The amount of time that proxy will wait for the entire request to be received. The timer is activated when the request is initiated, and is disarmed when the last byte of the request is sent, OR when the response is initiated. Setting this timeout to 0 will disable it. Default is 15s.
          - `streamIdleTimeout` string: StreamIdleTimeout is the amount of time that proxy will allow a stream to exist with no activity. Setting this timeout to 0 will disable it. Default is 30m
        - `idleTimeout` string: IdleTimeout is defined as the period in which there are no bytes sent or received on connection Setting this timeout to 0 will disable it. Be cautious when disabling it because it can lead to connection leaking. Default value is 1h.
      - `targetRef` object, required: TargetRef is a reference to the resource that represents a group of clients.
        - `kind` 'Mesh' | 'MeshSubset' | 'MeshGateway' | 'MeshService' | 'MeshExternalService' | 'MeshMultiZoneService' | 'MeshServiceSubset' | 'MeshHTTPRoute' | 'Dataplane', required: Kind of the referenced resource
        - `labels` object: Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.
        - `mesh` string: Mesh is reserved for future use to identify cross mesh resources.
        - `name` string: Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`
        - `namespace` string: Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.
        - `proxyTypes` string[]: ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.
        - `sectionName` string: SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
        - `tags` object: Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`
    - `rules` object[]: Rules defines inbound timeout configurations. When matches are present, the rule is applied only to traffic selected by the given source and destination matchers.
      - `default` object: Default contains configuration of the inbound timeouts
        - `connectionTimeout` string: ConnectionTimeout specifies the amount of time proxy will wait for an TCP connection to be established. Default value is 5 seconds. Cannot be set to 0.
        - `http` object: Http provides configuration for HTTP specific timeouts
          - `maxConnectionDuration` string: MaxConnectionDuration is the time after which a connection will be drained and/or closed, starting from when it was first established. Setting this timeout to 0 will disable it. Disabled by default.
          - `maxStreamDuration` string: MaxStreamDuration is the maximum time that a stream’s lifetime will span. Setting this timeout to 0 will disable it. Disabled by default.
          - `requestHeadersTimeout` string: RequestHeadersTimeout The amount of time that proxy will wait for the request headers to be received. The timer is activated when the first byte of the headers is received, and is disarmed when the last byte of the headers has been received. If not specified or set to 0, this timeout is disabled. Disabled by default.
          - `requestTimeout` string: RequestTimeout The amount of time that proxy will wait for the entire request to be received. The timer is activated when the request is initiated, and is disarmed when the last byte of the request is sent, OR when the response is initiated. Setting this timeout to 0 will disable it. Default is 15s.
          - `streamIdleTimeout` string: StreamIdleTimeout is the amount of time that proxy will allow a stream to exist with no activity. Setting this timeout to 0 will disable it. Default is 30m
        - `idleTimeout` string: IdleTimeout is defined as the period in which there are no bytes sent or received on connection Setting this timeout to 0 will disable it. Be cautious when disabling it because it can lead to connection leaking. Default value is 1h.
      - `matches` object[]: Matches define predicates for selecting traffic this configuration applies to.
        - `sni` object: SNI defines a matcher configuration for matching by SNI value carried on the TLS connection
          - `type` 'Exact', required: Type defines how to match traffic by SNI. Only `Exact` is supported.
          - `value` string, required: Value is the SNI carried on the TLS connection that needs to match for the configuration to be applied
        - `spiffeID` object: SpiffeID defines a matcher configuration for SpiffeID matching
          - `type` 'Exact' | 'Prefix', required: Type defines how to match incoming traffic by SpiffeID. `Exact` or `Prefix` are allowed.
          - `value` string, required: Value is SpiffeID of a client that needs to match for the configuration to be applied
    - `targetRef` object: TargetRef is a reference to the resource the policy takes an effect on. The resource could be either a real store object or virtual resource defined inplace.
      - `kind` 'Mesh' | 'MeshSubset' | 'MeshGateway' | 'MeshService' | 'MeshExternalService' | 'MeshMultiZoneService' | 'MeshServiceSubset' | 'MeshHTTPRoute' | 'Dataplane', required: Kind of the referenced resource
      - `labels` object: Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.
      - `mesh` string: Mesh is reserved for future use to identify cross mesh resources.
      - `name` string: Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`
      - `namespace` string: Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.
      - `proxyTypes` string[]: ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.
      - `sectionName` string: SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
      - `tags` object: Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`
    - `to` object[]: To list makes a match between the consumed services and corresponding configurations
      - `default` object: Default is a configuration specific to the group of destinations referenced in 'targetRef'
        - `connectionTimeout` string: ConnectionTimeout specifies the amount of time proxy will wait for an TCP connection to be established. Default value is 5 seconds. Cannot be set to 0.
        - `http` object: Http provides configuration for HTTP specific timeouts
          - `maxConnectionDuration` string: MaxConnectionDuration is the time after which a connection will be drained and/or closed, starting from when it was first established. Setting this timeout to 0 will disable it. Disabled by default.
          - `maxStreamDuration` string: MaxStreamDuration is the maximum time that a stream’s lifetime will span. Setting this timeout to 0 will disable it. Disabled by default.
          - `requestHeadersTimeout` string: RequestHeadersTimeout The amount of time that proxy will wait for the request headers to be received. The timer is activated when the first byte of the headers is received, and is disarmed when the last byte of the headers has been received. If not specified or set to 0, this timeout is disabled. Disabled by default.
          - `requestTimeout` string: RequestTimeout The amount of time that proxy will wait for the entire request to be received. The timer is activated when the request is initiated, and is disarmed when the last byte of the request is sent, OR when the response is initiated. Setting this timeout to 0 will disable it. Default is 15s.
          - `streamIdleTimeout` string: StreamIdleTimeout is the amount of time that proxy will allow a stream to exist with no activity. Setting this timeout to 0 will disable it. Default is 30m
        - `idleTimeout` string: IdleTimeout is defined as the period in which there are no bytes sent or received on connection Setting this timeout to 0 will disable it. Be cautious when disabling it because it can lead to connection leaking. Default value is 1h.
      - `targetRef` object, required: TargetRef is a reference to the resource that represents a group of destinations.
        - `kind` 'Mesh' | 'MeshSubset' | 'MeshGateway' | 'MeshService' | 'MeshExternalService' | 'MeshMultiZoneService' | 'MeshServiceSubset' | 'MeshHTTPRoute' | 'Dataplane', required: Kind of the referenced resource
        - `labels` object: Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.
        - `mesh` string: Mesh is reserved for future use to identify cross mesh resources.
        - `name` string: Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`
        - `namespace` string: Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.
        - `proxyTypes` string[]: ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.
        - `sectionName` string: SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
        - `tags` object: Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`
  - `creationTime` string, date-time: Time at which the resource was created
  - `modificationTime` string, date-time: Time at which the resource was updated

## Response `200`

Successful response

- object
  - `warnings` string[]: warnings is a list of warning messages to return to the requesting Kuma API clients. Warning messages describe a problem the client making the API request should correct or be aware of.

## Other responses

- `201`: Successful response

## Changes

- **2026-08-18** `658ffb748f95`: 1 info
  - added the new optional request property `spec/rules/items/matches`
- **2025-08-12** `b2800570b3e2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kong/apis/konnect-api-beta/changes/v1/mesh/control-planes/:cpId/api/meshes/:mesh/meshtimeouts/:name/put.md)

---

[API](https://skmtc.dev/kong/apis/konnect-api-beta.md) - [All operations](https://skmtc.dev/kong/apis/konnect-api-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-beta/revisions/cef0f947e9c9?raw)