> ## 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 API

> Reference for Conduktor Gateway's endpoint that produces Kafka records over REST: requirements, request and response fields, partitioning, errors and differences from Confluent REST Proxy v3.

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

`POST /gateway/v2/topics/{topic}/records` produces Kafka records to a topic through Gateway, without a Kafka client. 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.

Gateway serves the endpoint on a [listener of its own](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/environment-variables.md#records-api), on port `8889` by default, with its own TLS settings.

To produce your first records, follow [produce records over REST](https://docs.conduktor.io/guide/tutorials/produce-records-over-rest.md). The endpoint is also listed in the [Gateway API reference](https://developers.conduktor.io/?product=gateway\&gatewayApiVersion=v2).

## How it works

The endpoint takes the caller's Kafka credentials as HTTP basic authentication. Gateway uses them as the SASL/PLAIN credentials of a producer that connects to Gateway's own `SASL_PLAINTEXT` listener. The same authentication, ACLs, Virtual Cluster and Interceptors apply as for any other Kafka client connecting to Gateway.

```mermaid theme={null}
sequenceDiagram
    Client->>Gateway records API: POST /gateway/v2/topics/{topic}/records (user:password)
    Gateway records API->>Gateway Kafka listener: Producer, SASL/PLAIN user:password
    Gateway Kafka listener->>Kafka: Produce (authentication, ACLs, Interceptors)
    Gateway records API-->>Client: Partition and offset of each record
```

## Requirements

| Requirement | Details |
| - | - |
| **Feature flag** | Set `GATEWAY_FEATURE_FLAGS_RECORDS_API` to `true`. |
| **`SASL_PLAINTEXT` listener** | Gateway produces through the first [listener](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/listener-security.md#sasl_plaintext) that uses `SASL_PLAINTEXT`. With the feature flag on, Gateway doesn't start without one. |
| **SASL/PLAIN credentials** | In [`GATEWAY_MANAGED`](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/listener-security#gateway_managed) mode, Gateway doesn't start without `GATEWAY_USER_POOL_SECRET_KEY`, and callers use a [local service account and its token](https://docs.conduktor.io/guide/tutorials/manage-gateway-service-accounts.md). In [`KAFKA_MANAGED`](https://docs.conduktor.io/guide/conduktor-in-production/deploy-artifacts/deploy-gateway/listener-security#kafka_managed) mode, the backing Kafka cluster has to enable SASL/PLAIN. Gateway can't check this on startup. |

The producer connects to the listener's bind address, or to `localhost` when the listener binds every interface, then follows the advertised addresses. Gateway itself has to be able to reach these addresses.

## Request

The body holds one record object, or several record objects one after the other. Gateway writes the records in the order they appear.

| Field | Required | Description |
| - | - | - |
| `key` | No | The record key, as an object with `type` and `data`. |
| `value` | No | The record value, as an object with `type` and `data`. When absent or `data` is `null`, the record is a tombstone. |
| `headers` | No | A list of headers, each with a `name` and a base64-encoded `value`. |
| `partitionId` | No | The partition to write to. When absent, see [partitioning](#partitioning). |
| `timestamp` | No | The record timestamp, in ISO 8601 format. |

`type` is mandatory in `key` and `value`, and takes one of these values:

| Type | `data` format |
| - | - |
| `BINARY` | Base64-encoded bytes. |
| `STRING` | A string, sent as UTF-8. |
| `JSON` | Any JSON value, sent as compact JSON text. |

Schema Registry types aren't supported and return `400`. Gateway ignores unknown fields.

### Partitioning

Without `partitionId`, the Java client's default partitioner picks the partition: a hash of the key bytes for keyed records, sticky partitioning for records without a key. A librdkafka client producing the same key can pick another partition.

## Response

Gateway returns one result per record, in the same order as the request.

| Field | Description |
| - | - |
| `errorCode` | `200` for a record that was written. |
| `topicName` | The topic the record was written to. |
| `partitionId` | The partition the record was written to. |
| `offset` | The record's offset in that partition. |
| `timestamp` | The record timestamp. |
| `key` | The key's `type` and its `size` in bytes. Absent when the key is `null`. |
| `value` | The value's `type` and its `size` in bytes. Absent when the value is `null`. |

## Errors

With a single record, the record's error is the HTTP response:

| Status | Cause |
| - | - |
| `400` | An Interceptor refused the record, or the request is invalid, for example an unsupported `type` or invalid base64. |
| `401` | The credentials are missing, or SASL authentication with them failed. |
| `403` | An ACL denies the caller. |
| `413` | The body is larger than `GATEWAY_RECORDS_API_MAX_BODY_SIZE`, 10 MiB by default. |
| `500` | The topic or partition doesn't exist. Gateway waits 10 seconds for it before returning this error. |

The body uses the Gateway API's error format:

```json theme={null}
{"title":"Not authorized to access topics: [orders]"}
```

With several records, 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. A failed record gets an error in place of its result:

```json theme={null}
{"errorCode":400,"message":"value: invalid base64"}
```

## Differences from Confluent REST Proxy v3

The request and response fields follow [Confluent REST Proxy v3](https://docs.confluent.io/platform/current/kafka-rest/api.html#records-v3), with these differences:

* Fields are in camelCase and the response has no `cluster_id`.
* The path has no `/v3/clusters/{cluster_id}` segment.
* `type` is mandatory in `key` and `value`.
* Gateway reads the whole body before producing, rather than streaming it.
* A single-record error, or an error about the whole request, uses the Gateway API's `{"title": ...}` format.

## Related resources

* [Produce records over REST](https://docs.conduktor.io/guide/tutorials/produce-records-over-rest.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.