Test Pipe
POST /public/v1/pipes/test
Checks with one record whether a pipe would work. The request reads a record from the source topic and takes it through the pipe: decoding, the processing of the topic view, and encoding for the target topic.
Nothing is written, no position is committed and no pipe is created.
Request
The body is the same as for Create Pipe. The same rights are checked.
Example Request
curl --location 'https://your-instance.com/public/v1/pipes/test' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-api-key>' \
--data-raw '{
"name": "Fix account ids",
"mode": "ONCE",
"source": { "serverId": 1, "viewId": 42 },
"target": { "serverId": 1, "topic": "payments" },
"configuration": {
"target": { "keyCodec": "String", "valueCodec": "Json" }
}
}'
Response
HTTP Status Code: 200 OK
The status code is 200 whether the test passed or not. Check the field ok.
| Field | Type | Description |
|---|---|---|
ok | boolean | true if a record made it through all stages |
scanned | integer | Number of records read during the test. Up to 500 records are read to find one that passes the filters of the view. |
stages | array of objects (Stage) | The stages of the test, in their order, up to the one that failed |
output | object | With ok true: the record the pipe would write |
input | object | With a failed stage: the record it failed on, as far as it was decoded |
Stage Structure
| Field | Type | Description |
|---|---|---|
stage | string | source, target, decode, process, encode, or setup for a problem before the first record |
ok | boolean | Whether the stage passed |
message | string | What was checked, or what went wrong |
Output Structure
| Field | Type | Description |
|---|---|---|
record | object | The record after the processing of the view, as the Data Explorer shows it |
headers | array of objects | The headers that would be written: key, value |
keyBytes | integer | Size of the encoded key in bytes, -1 without a key |
valueBytes | integer | Size of the encoded value in bytes, -1 without a value |
Example Response — Passed
{
"ok": true,
"scanned": 1,
"stages": [
{ "stage": "source", "ok": true, "message": "The source topic can be read." },
{ "stage": "target", "ok": true, "message": "The target topic exists." },
{ "stage": "decode", "ok": true, "message": "The record can be decoded." },
{ "stage": "process", "ok": true, "message": "The processing of the topic view runs." },
{ "stage": "encode", "ok": true, "message": "The result can be written with the codecs of the target." }
],
"output": {
"record": {
"topic": "payments.dlq",
"partition": 0,
"offset": 118,
"timestamp": 1794536317279,
"key": "DE4410",
"value": { "accountId": "DE4410", "amount": 120.0 },
"keyDecoder": "String",
"valueDecoder": "Json"
},
"headers": [],
"keyBytes": 6,
"valueBytes": 39
}
}
Example Response — Failed
{
"ok": false,
"scanned": 0,
"stages": [
{ "stage": "source", "ok": true, "message": "The source topic can be read." },
{ "stage": "setup", "ok": false, "message": "The target topic 'payments' cannot be reached: UnknownTopicOrPartitionException: This server does not host this topic-partition." }
]
}
Possible Errors
| Status Code | Description | Solution |
|---|---|---|
| 400 | The request body is not valid | Check the request body |
| 401 | Unauthorized | Check your API key |
| 403 | The API key lacks a right for a topic or the Schema Registry | Check the rights of the API key |
| 404 | A connection or the saved view does not exist or is not visible | Check the IDs |
Best Practices
- Run the test in your deployment pipeline before every Create Pipe request, and stop if
okisfalse. - A test needs at least one record in the part of the source topic the pipe would read. With an empty topic the stage
decodefails with a message that says so.