---
title: "Create Consume Policy for Virtual Cluster"
method: POST
path: "/v1/event-gateways/{gatewayId}/virtual-clusters/{virtualClusterId}/consume-policies#Transcode"
tags: ["Event Gateway Virtual Cluster Consume Policies"]
---

# Create Consume Policy for Virtual Cluster

`POST /v1/event-gateways/{gatewayId}/virtual-clusters/{virtualClusterId}/consume-policies#Transcode`

## Request

- Base URL: `https://global.api.konghq.com`
- URL: `https://global.api.konghq.com/v1/event-gateways/{gatewayId}/virtual-clusters/{virtualClusterId}/consume-policies#Transcode`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

Creates a new consume policy associated with the specified Event Gateway virtual cluster.

## Query parameters

- `before` string, uuid
- `after` string, uuid

## Request body

- EventGatewayParsedRecordTranscodeConsumePolicyCreate: Converts an already schema-validated record value into a different serialization format before it is returned to the consumer. Note this policy can only be used as a child of a `EventGatewayConsumeSchemaValidationPolicy` policy. **Requires a minimum runtime version of `1.3`**.
  - `type` 'transcode', required: The type name of the policy.
  - `name` string: A unique user-defined name of the policy.
  - `description` string: A human-readable description of the policy.
  - `enabled` boolean: Whether the policy is enabled.
  - `labels` Labels: Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
  - `config` union, required: The configuration of the transcode parsed record policy applied to consumed records.
    - EventGatewayParsedRecordTranscodeConsumeConfigJson: The configuration of the transcode parsed record policy when converting consumed records to JSON.
      - `failure_mode` 'error' | 'skip' | 'passthrough' | 'mark', required: Describes how to handle a failure in a policy applied to consumed records. * `error` - the batch is not delivered to the client. Use sparingly: erroring on a batch causes clients to get stuck on the problematic offset and requires manual intervention to skip it. * `skip` - the record is not delivered to the client. * `passthrough` - passes the record to the client even though policy execution failed. * `mark` - passes the record to the client but marks it with a `kong/policy-failure-<id>` header whose value is the reason for the policy failure (truncated to 512 characters). **Requires a minimum runtime version of `1.2`**.
      - `on_unknown_field` 'fail' | 'drop': Describes how to handle JSON fields that are not defined in the target schema. * `fail` - the transcoding fails. The policy `failure_mode` determines how the failure is handled. * `drop` - the unknown fields are removed from the transcoded value. **Requires a minimum runtime version of `1.3`**.
      - `schema_source` union: Determines how to look up the schema to use for the transcoded output data. Leave this unset if the output data schema isn't needed.
        - EventGatewayParsedRecordTranscodeSchemaSourceReference: References a schema registered in a schema registry, computing the subject and version to use.
          - `type` 'reference', required
          - `schema_registry` SchemaRegistryReference, required
            - `id` string, uuid, required: The unique identifier of the schema registry.
          - `subject` string, required: An expression that computes the schema registry subject of the output data's schema.
          - `version` string, required: An expression that computes the schema registry version of the output data's schema.
          - `schema_ref_destination` union, required: Defines how to record the schema id for the transcoded output data. See the [Confluent docs](https://docs.confluent.io/platform/current/schema-registry/fundamentals/serdes-develop/index.html#wire-format) for more about the wire format.
            - EventGatewayParsedRecordTranscodeSchemaRefDestinationConfluentFormat: Prefixes the structured data bytes with a reference to the schema.
              - …
            - EventGatewayParsedRecordTranscodeSchemaRefDestinationRecordHeader: Puts the schema reference in a record header.
              - …
            - EventGatewayParsedRecordTranscodeSchemaRefDestinationNone: Do not persist the schema anywhere.
              - …
        - EventGatewayParsedRecordTranscodeSchemaSourceInline: A schema embedded directly in the policy configuration.
          - `type` 'inline', required
          - `inline` string, required: The raw schema text (e.g. an Avro JSON schema) to use for the transcoded output data.
      - `output_format` 'json', required: The serialization format to convert the record value into.
    - EventGatewayParsedRecordTranscodeConsumeConfigAvro: The configuration of the transcode parsed record policy when converting consumed records to Avro. Avro requires a schema to serialize the record value, so `schema_source` must be set.
      - `failure_mode` 'error' | 'skip' | 'passthrough' | 'mark', required: Describes how to handle a failure in a policy applied to consumed records. * `error` - the batch is not delivered to the client. Use sparingly: erroring on a batch causes clients to get stuck on the problematic offset and requires manual intervention to skip it. * `skip` - the record is not delivered to the client. * `passthrough` - passes the record to the client even though policy execution failed. * `mark` - passes the record to the client but marks it with a `kong/policy-failure-<id>` header whose value is the reason for the policy failure (truncated to 512 characters). **Requires a minimum runtime version of `1.2`**.
      - `on_unknown_field` 'fail' | 'drop': Describes how to handle JSON fields that are not defined in the target schema. * `fail` - the transcoding fails. The policy `failure_mode` determines how the failure is handled. * `drop` - the unknown fields are removed from the transcoded value. **Requires a minimum runtime version of `1.3`**.
      - `schema_source` union, required: Determines how to look up the schema to use for the transcoded output data. Leave this unset if the output data schema isn't needed.
        - EventGatewayParsedRecordTranscodeSchemaSourceReference: References a schema registered in a schema registry, computing the subject and version to use.
          - `type` 'reference', required
          - `schema_registry` SchemaRegistryReference, required
            - `id` string, uuid, required: The unique identifier of the schema registry.
          - `subject` string, required: An expression that computes the schema registry subject of the output data's schema.
          - `version` string, required: An expression that computes the schema registry version of the output data's schema.
          - `schema_ref_destination` union, required: Defines how to record the schema id for the transcoded output data. See the [Confluent docs](https://docs.confluent.io/platform/current/schema-registry/fundamentals/serdes-develop/index.html#wire-format) for more about the wire format.
            - EventGatewayParsedRecordTranscodeSchemaRefDestinationConfluentFormat: Prefixes the structured data bytes with a reference to the schema.
              - …
            - EventGatewayParsedRecordTranscodeSchemaRefDestinationRecordHeader: Puts the schema reference in a record header.
              - …
            - EventGatewayParsedRecordTranscodeSchemaRefDestinationNone: Do not persist the schema anywhere.
              - …
        - EventGatewayParsedRecordTranscodeSchemaSourceInline: A schema embedded directly in the policy configuration.
          - `type` 'inline', required
          - `inline` string, required: The raw schema text (e.g. an Avro JSON schema) to use for the transcoded output data.
      - `output_format` 'avro', required: The serialization format to convert the record value into.
  - `condition` string: A string containing the boolean expression that determines whether the policy is applied. When the policy is applied as a child policy of schema_validation, the expression can also reference `record.value` fields.
  - `parent_policy_id` string, uuid, required: The unique identifier of the parent schema validation policy.

## Response `201`

Created

- EventGatewayConsumePolicyTranscodeTFOnly: A policy associated with an Event Gateway.
  - `type` string, required: The type name of the policy.
  - `name` string: A unique user-defined name of the policy.
  - `description` string: A human-readable description of the policy.
  - `enabled` boolean: Whether the policy is enabled.
  - `labels` Labels: Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
  - `id` string, uuid, required: The unique identifier of the policy.
  - `config` object, required: The configuration of the policy.
  - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date.
  - `parent_policy_id` string, uuid, nullable: The unique identifier of the parent policy, if any.
  - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity update date.
  - `condition` string: A string containing the boolean expression that determines whether the policy is applied.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden

## Changes

- **2026-11-05** `f018071a4515`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kong/apis/konnect-api/changes/v1/event-gateways/:gatewayId/virtual-clusters/:virtualClusterId/consume-policies%23Transcode/post.md)

---

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