# Streams API

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [connect-full.txt](https://docs.redpanda.com/connect-full.txt)

---
title: Streams API
latest-connect-version: 4.93.0
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-redpanda-tag: v26.1.9
docname: streams_mode/streams_api
page-component-name: connect
page-version: master
page-component-version: master
page-component-title: Connect
page-relative-src-path: streams_mode/streams_api.adoc
page-edit-url: https://github.com/redpanda-data/rp-connect-docs/edit/main/modules/guides/pages/streams_mode/streams_api.adoc
description: Get an overview of streams mode in Redpanda Connect, detailing its features, use cases, and setup instructions.
page-git-created-date: "2024-05-24"
page-git-modified-date: "2024-09-05"
---

<!-- Source: https://docs.redpanda.com/connect/guides/streams_mode/streams_api.md -->

When Redpanda Connect is run in `streams` mode it will open up an HTTP REST API for creating and managing independent streams of data instead of creating a single stream.

Each stream has its own input, buffer, pipeline and output sections which contains an isolated stream of data with its own lifetime. A stream config cannot include [resources](https://docs.redpanda.com/connect/configuration/resources/), and instead these should be created and modified using the `/resources/{type}/{id}` endpoint.

A walkthrough on using this API [can be found here](https://docs.redpanda.com/connect/guides/streams_mode/using_rest_api/).

## [](#api)API

### [](#get-ready)GET `/ready`

Returns a 200 OK response if all active streams are connected to their respective inputs and outputs at the time of the request. Otherwise, a 503 response is returned along with a message naming the faulty stream.

If zero streams are active this endpoint still returns a 200 OK response.

### [](#get-streams)GET `/streams`

Returns a map of existing streams by their unique identifiers to an object showing their status and uptime.

#### [](#response-200)Response 200

```json
{
	"<string, stream id>": {
		"active": "<bool, whether the stream is running>",
		"uptime": "<float, uptime in seconds>",
		"uptime_str": "<string, human readable string of uptime>"
	}
}
```

### [](#post-streams)POST `/streams`

Sets the entire collection of streams to the body of the request. Streams that exist but aren’t within the request body are _removed_, streams that exist already and are in the request body are updated, other streams within the request body are created.

```json
{
	"<string, stream id>": "<object, a standard Redpanda Connect stream configuration>"
}
```

#### [](#response-200-2)Response 200

The streams were updated successfully.

#### [](#response-400)Response 400

A configuration was invalid, or has linting errors. If linting errors were detected then a JSON response is provided of the form:

```json
{
	"linting_errors": [
		"<a description of the error"
	]
}
```

If you wish for the streams API to proceed with configurations that contain linting errors then you can override this check by setting the URL param `chilled` to `true`, e.g. `/streams?chilled=true`.

### [](#post-streamsid)POST `/streams/{id}`

Create a new stream identified by `id` by posting a body containing the stream configuration in either JSON or YAML format. The configuration should be a standard Redpanda Connect configuration containing the sections `input`, `buffer`, `pipeline` and `output`.

#### [](#request-body-example)Request body example

URL: `/streams/foo`

```yaml
input:
  file:
    paths: [ /tmp/input.ndjson ]
pipeline:
  processors:
    - mapping: root = content().uppercase()
output:
  file:
    path: /tmp/output.ndjson
```

#### [](#response-200-3)Response 200

The stream was created successfully.

#### [](#response-400-2)Response 400

The configuration was invalid, or has linting errors. If linting errors were detected then a JSON response is provided of the form:

```json
{
	"linting_errors": [
		"<a description of the error"
	]
}
```

If you wish for the streams API to proceed with configurations that contain linting errors then you can override this check by setting the URL param `chilled` to `true`, e.g. `/streams/foo?chilled=true`.

### [](#get-streamsid)GET `/streams/{id}`

Read the details of an existing stream identified by `id`.

#### [](#response-200-4)Response 200

```json
{
	"active": "<bool, whether the stream is running>",
	"uptime": "<float, uptime in seconds>",
	"uptime_str": "<string, human readable string of uptime>",
	"config": "<object, the configuration of the stream>"
}
```

### [](#put-streamsid)PUT `/streams/{id}`

Update an existing stream identified by `id` by posting a body containing the new stream configuration in either JSON or YAML format. The configuration should be a standard Redpanda Connect configuration containing the sections `input`, `buffer`, `pipeline` and `output`.

The previous stream will be shut down before and a new stream will take its place.

#### [](#response-200-5)Response 200

The stream was updated successfully.

#### [](#response-400-3)Response 400

The configuration was invalid, or has linting errors. If linting errors were detected then a JSON response is provided of the form:

```json
{
	"linting_errors": [
		"<a description of the error"
	]
}
```

If you wish for the streams API to proceed with configurations that contain linting errors then you can override this check by setting the URL param `chilled` to `true`, e.g. `/streams/foo?chilled=true`.

### [](#patch-streamsid)PATCH `/streams/{id}`

Update an existing stream identified by `id` by posting a body containing only changes to be made to the existing configuration. The existing configuration will be patched with the new fields and the stream restarted with the result.

#### [](#response-200-6)Response 200

The stream was patched successfully.

### [](#delete-streamsid)DELETE `/streams/{id}`

Attempt to shut down and remove a stream identified by `id`.

#### [](#response-200-7)Response 200

The stream was found, shut down and removed successfully.

### [](#get-streamsidstats)GET `/streams/{id}/stats`

Read the metrics of an existing stream as a hierarchical JSON object.

#### [](#response-200-8)Response 200

The stream was found.

### [](#post-resourcestypeid)POST `/resources/{type}/{id}`

Add or modify a resource component configuration of a given `type` identified by a unique `id`. The configuration must be in JSON or YAML format and must only contain configuration fields for the component.

Valid component types are `cache`, `input`, `output`, `processor` and `rate_limit`.

#### [](#request-body-example-2)Request body example

URL: `/resources/cache/foo`

```yml
redis:
  url: http://localhost:6379
  expiration: 1h
```

#### [](#response-200-9)Response 200

The resource was created successfully.

#### [](#response-400-4)Response 400

The configuration was invalid, or has linting errors. If linting errors were detected then a JSON response is provided of the form:

```json
{
	"linting_errors": [
		"<a description of the error"
	]
}
```

If you wish for the streams API to proceed with configurations that contain linting errors then you can override this check by setting the URL param `chilled` to `true`, e.g. `/resources/cache/foo?chilled=true`.