Skip to content
|
search
Plugin Hub
header icon

jq

The jq plugin enables arbitrary jq transformations on JSON objects included in API requests or responses.

The configuration accepts two sets of options: one for the request and another for the response. For both the request and response, a jq program string can be included, along with some jq option flags and a list of media types.

One of the configured media types must be included in the Content-Type header of the request or response for the jq program to run. The default media type in the Content-Type header is application/json.

In the response context, you can also specify a list of status codes, one of which must match the response status code. The default response status code is 200.

Notes:

  • In the response context the entire body must be buffered to be processed. This requirement also implies that the Content-Length header will be dropped if present, and the body transferred with chunked encoding.
  • To use this plugin in Konnect, upgrade your runtimes to at least v2.6.0.0.

See jq’s documentation on Basic filters for more information on writing programs with jq.

Configuration Reference

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter Description
name
required

Type: string		 The name of the plugin, in this case jq.
service.name or service.id

Type: string		 The name or ID of the service the plugin targets.

Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.

Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins.
route.name or route.id

Type: string		 The name or ID of the route the plugin targets.

Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.

Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins.
consumer.name or consumer.id

Type: string		 The name or ID of the consumer the plugin targets.

Set one of these parameters if adding the plugin to a consumer through the top-level /plugins endpoint.

Not required if using /consumers/CONSUMER_NAME|CONSUMER_ID/plugins.
enabled

Type: boolean

Default value: true		 Whether this plugin will be applied.
config.request_jq_program
semi-optional

Type: string

The jq program to run on the request body. For example, .[0] | { "X-Foo": .foo }. Either request_jq_program or response_jq_plugin must be included in the configuration.
config.request_jq_program_options
optional

Type: record

Boolean option flags to modify the run behavior of the jq program run on the request body.

  • compact_output: Returns output in a compact form without additional spacing, and with each JSON object on a single line. Defaults to true. Set to false for “pretty” output.
  • raw_output: Outputs as raw strings, not JSON quoted. Default is false.
  • join_output: Similar to raw_output but does not output newline separators. Default is false.
  • ascii_output: jq usually outputs non-ASCII Unicode codepoints as UTF-8, even if the input specified them as escape sequences (like \u03bc). Using this option, you can force jq to produce pure ASCII output, replacing every non-ASCII character with the equivalent escape sequence. Default is false.
  • sort_keys: Outputs the fields of each object with the keys in sorted order. Default is false.
config.request_if_media_type
optional

Type: array of strings

Default value: [“application/json”]

A list of media type strings. The media type included in the Content-Type request header must match one of the media types on this list for the program to run.
config.response_jq_program
semi-optional

Type: string

The jq program to run on the response body. For example, .[0] | { "X-Foo": .foo }. Either request_jq_program or response_jq_plugin must be included in configuration.
config.response_jq_program_options
optional

Type: record

Boolean option flags to modify the run behavior of the jq program run on the response body.

  • compact_output: Returns output in a compact form without additional spacing, and with each JSON object on a single line. Defaults to true. Set to false for “pretty” output.
  • raw_output: Outputs as raw strings, not JSON quoted. Default is false.
  • join_output: Similar to raw_output but does not output newline separators. Default is false.
  • ascii_output: jq usually outputs non-ASCII Unicode codepoints as UTF-8, even if the input specified them as escape sequences (like \u03bc). Using this option, you can force jq to produce pure ASCII output, replacing every non-ASCII character with the equivalent escape sequence. Default is false.
  • sort_keys: Outputs the fields of each object with the keys in sorted order. Default is false.
config.response_if_media_type
optional

Type: array of strings

Default value: [“application/json”]

A list of media type strings. The media type included in the Content-Type response header must match one of the media types on this list for the program to run.
config.response_if_status_code
optional

Type: array of integers

Default value: [200]

A list of HTTP response status codes. The response status code must match one of the response status codes on this list for the program to run.