> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduktor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Produce records over REST

> Produce Kafka records through Conduktor Gateway with an HTTP request. Gateway applies the caller's authentication, ACLs, Virtual Cluster and Interceptors.

[Preview](https://docs.conduktor.io/guide/reference/feature-labels.md#preview) (On its way to general availability (GA). Try it now. It may change before GA and isn't recommended for production yet.)

This feature is in preview from Gateway 3.23.0. It's disabled by default and its request and response format can change between releases.

Send Kafka records to a topic with an HTTP `POST` to Gateway's records API, without a Kafka client. Gateway produces each record as the caller, so the same authentication, ACLs, Virtual Cluster and Interceptors apply as for any other Kafka client connecting to Gateway.

## Before you start

* `GATEWAY_FEATURE_FLAGS_RECORDS_API` set to `true`.
* Access to the [records API listener](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/environment-variables.md#records-api), on port `8889` by default.
* A `SASL_PLAINTEXT` listener on Gateway. Gateway produces as the caller through this listener.
* SASL/PLAIN credentials for the caller.

The [requirements](https://docs.conduktor.io/guide/reference/produce-records-api.md#requirements) explain each of these and what Gateway checks on startup.

## Produce a record

**1. Get credentials**

Use the Kafka credentials the client would use against Gateway. They depend on Gateway's [security mode](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/listener-security.md#security-mode), set by `GATEWAY_SECURITY_MODE`:

* In [`KAFKA_MANAGED`](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/listener-security#kafka_managed) mode, the backing Kafka cluster checks the credentials. Use a SASL/PLAIN user and password from that cluster.
* In [`GATEWAY_MANAGED`](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/listener-security#gateway_managed) mode, Gateway checks the credentials. Create a local service account and generate a token for it:

```bash theme={null}
curl -u <ADMIN_USER>:<ADMIN_PASSWORD> -X PUT http://<GATEWAY_HOST>:8888/gateway/v2/service-account \
  -H 'Content-Type: application/json' \
  -d '{"kind":"GatewayServiceAccount","apiVersion":"gateway/v2","metadata":{"name":"alice","vCluster":"passthrough"},"spec":{"type":"LOCAL"}}'

TOKEN=$(curl -s -u <ADMIN_USER>:<ADMIN_PASSWORD> -X POST http://<GATEWAY_HOST>:8888/gateway/v2/token \
  -H 'Content-Type: application/json' \
  -d '{"vCluster":"passthrough","username":"alice","lifeTimeSeconds":3600}' | jq -r .token)
```

**2. Send the record**

Produce a JSON value with a string key and an example header. Header values are base64-encoded, and `cmVzdA==` is `rest`:

```bash theme={null}
curl -u "alice:$TOKEN" -X POST http://<GATEWAY_HOST>:8889/gateway/v2/topics/orders/records \
  -H 'Content-Type: application/json' \
  -d '{"key":{"type":"STRING","data":"order-1"},
       "value":{"type":"JSON","data":{"id":1}},
       "headers":[{"name":"source","value":"cmVzdA=="}]}'
```

**3. Check the response**

Gateway returns the topic, partition and offset the record was written to:

```json theme={null}
{
  "errorCode": 200,
  "topicName": "orders",
  "partitionId": 0,
  "offset": 42,
  "timestamp": "2026-10-08T15:43:37.595Z",
  "key": {"type": "STRING", "size": 7},
  "value": {"type": "JSON", "size": 8}
}
```

> [!TIP]
>
> Gateway returns the response on a single line. To format it, add `-s` to the `curl` command and pipe the output to `jq`:
>
> ```bash theme={null}
> curl -s -u "alice:$TOKEN" -X POST http://<GATEWAY_HOST>:8889/gateway/v2/topics/orders/records ... | jq
> ```

## Produce several records in one request

Put several record objects one after the other in the body. Gateway returns one result per record, in the same order, and writes the records in that order:

```bash theme={null}
curl -u "alice:$TOKEN" -X POST http://<GATEWAY_HOST>:8889/gateway/v2/topics/orders/records \
  -H 'Content-Type: application/json' \
  --data-binary $'{"value":{"type":"STRING","data":"first"}}\n{"value":{"type":"BINARY","data":"%%%"}}\n{"value":{"type":"STRING","data":"third"}}'
```

A record that fails doesn't stop the others. The HTTP status of the response is still `200`, so check the `errorCode` of each result: `200` means the record was written, any other value means it failed, with the reason in `message`:

```json theme={null}
{"errorCode":200,"topicName":"orders","partitionId":0,"offset":43,"timestamp":"2026-10-09T16:55:01.120Z","value":{"type":"STRING","size":5}}
{"errorCode":400,"message":"value: invalid base64"}
{"errorCode":200,"topicName":"orders","partitionId":0,"offset":44,"timestamp":"2026-10-09T16:55:01.121Z","value":{"type":"STRING","size":5}}
```

## Next steps

For every request and response field, the error codes and the differences from Confluent REST Proxy v3, see the [produce records API reference](https://docs.conduktor.io/guide/reference/produce-records-api.md).

## Related resources

* [Manage Gateway service accounts and ACLs](https://docs.conduktor.io/guide/tutorials/manage-gateway-service-accounts.md)
* [Gateway listener security](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/listener-security.md)
* [Gateway feature flags](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/environment-variables.md#feature-flags)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.