Environments
Manage Lenses environments and configurations
Lists all environments
The bearer token can be obtained by creating a ServiceAccount.
Happy response.
Error object.
GET /api/v1/environments HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-11-15T12:51:44.793Z",
"tier": "development",
"status": {
"agent_connected": true,
"agent": {
"updated_at": "2025-11-15T12:51:44.793Z",
"roundtrip_duration": 1,
"agent": {
"hostname": "text",
"version": "text",
"protocol_version": "text",
"capabilities": {
"metrics": true,
"k2k": true,
"publish": true
}
},
"metrics": {
"kafka": {
"version": "text",
"num_brokers": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"data": {
"num_topics": 1,
"num_partitions": 1,
"num_schemas": 1,
"num_policies": 1,
"topic_data_total_bytes": 1,
"data_in_bytes_per_sec": 1,
"data_out_bytes_per_sec": 1,
"data_in_messages_per_sec": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"apps": {
"num_consumers": 1,
"num_other_apps": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"connect": {
"num_clusters": 1,
"num_connectors": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"other": {
"num_issues": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
}
}
}
},
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}Creates a new environment.
The bearer token can be obtained by creating a ServiceAccount.
Sets the name of the new environment. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.
Sets the display name of the new environment. If not provided, the value of "name" will be used.
Enumerates Tiers.
Happy response.
Error object.
POST /api/v1/environments HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 104
{
"name": "text",
"display_name": "text",
"tier": "development",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-11-15T12:51:44.793Z",
"tier": "development",
"status": {
"agent_connected": true,
"agent": {
"updated_at": "2025-11-15T12:51:44.793Z",
"roundtrip_duration": 1,
"agent": {
"hostname": "text",
"version": "text",
"protocol_version": "text",
"capabilities": {
"metrics": true,
"k2k": true,
"publish": true
}
},
"metrics": {
"kafka": {
"version": "text",
"num_brokers": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"data": {
"num_topics": 1,
"num_partitions": 1,
"num_schemas": 1,
"num_policies": 1,
"topic_data_total_bytes": 1,
"data_in_bytes_per_sec": 1,
"data_out_bytes_per_sec": 1,
"data_in_messages_per_sec": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"apps": {
"num_consumers": 1,
"num_other_apps": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"connect": {
"num_clusters": 1,
"num_connectors": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"other": {
"num_issues": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
}
}
}
},
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"agent_key": "text"
}Retrieves a single environment by name.
The bearer token can be obtained by creating a ServiceAccount.
Happy response.
Error object.
GET /api/v1/environments/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-11-15T12:51:44.793Z",
"tier": "development",
"status": {
"agent_connected": true,
"agent": {
"updated_at": "2025-11-15T12:51:44.793Z",
"roundtrip_duration": 1,
"agent": {
"hostname": "text",
"version": "text",
"protocol_version": "text",
"capabilities": {
"metrics": true,
"k2k": true,
"publish": true
}
},
"metrics": {
"kafka": {
"version": "text",
"num_brokers": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"data": {
"num_topics": 1,
"num_partitions": 1,
"num_schemas": 1,
"num_policies": 1,
"topic_data_total_bytes": 1,
"data_in_bytes_per_sec": 1,
"data_out_bytes_per_sec": 1,
"data_in_messages_per_sec": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"apps": {
"num_consumers": 1,
"num_other_apps": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"connect": {
"num_clusters": 1,
"num_connectors": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"other": {
"num_issues": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
}
}
}
},
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}Deletes an environment.
The bearer token can be obtained by creating a ServiceAccount.
Successful deletion.
Error object.
DELETE /api/v1/environments/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Updates an environment.
The bearer token can be obtained by creating a ServiceAccount.
Enumerates Tiers.
Updates the display name of the environment.
Happy response.
Error object.
PATCH /api/v1/environments/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90
{
"tier": "development",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"display_name": "text"
}{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-11-15T12:51:44.793Z",
"tier": "development",
"status": {
"agent_connected": true,
"agent": {
"updated_at": "2025-11-15T12:51:44.793Z",
"roundtrip_duration": 1,
"agent": {
"hostname": "text",
"version": "text",
"protocol_version": "text",
"capabilities": {
"metrics": true,
"k2k": true,
"publish": true
}
},
"metrics": {
"kafka": {
"version": "text",
"num_brokers": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"data": {
"num_topics": 1,
"num_partitions": 1,
"num_schemas": 1,
"num_policies": 1,
"topic_data_total_bytes": 1,
"data_in_bytes_per_sec": 1,
"data_out_bytes_per_sec": 1,
"data_in_messages_per_sec": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"apps": {
"num_consumers": 1,
"num_other_apps": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"connect": {
"num_clusters": 1,
"num_connectors": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"other": {
"num_issues": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
}
}
}
},
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}Lists Kafka connections defined for an Environment.
The bearer token can be obtained by creating a ServiceAccount.
Happy response.
Error object.
GET /api/v1/environments/{env_name}/kafka-connections HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"description": "text",
"created_at": "2025-11-15T12:51:44.793Z",
"override_broker_addresses": [
"text"
],
"auth": {}
}
]
}Retrieves a Kafka connection defined for an Environment.
The bearer token can be obtained by creating a ServiceAccount.
Happy response.
Error object.
GET /api/v1/environments/{env_name}/kafka-connections/{conn_name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"name": "text",
"display_name": "text",
"lrn": "text",
"description": "text",
"created_at": "2025-11-15T12:51:44.793Z",
"override_broker_addresses": [
"text"
],
"auth": {}
}Upserts a particular Environment's Kafka connection.
The bearer token can be obtained by creating a ServiceAccount.
Creates/updates a Kafka connection.
Sets the display name of the new KafkaConnection. If not provided, the value of "name" will be used.
Has the optional description of the object.
Optionally overrides the broker addresses. If not set, those of the agent are used.
Contains auth settings specific to a particular auth type.
Configures Kafka Plaintext "authentication".
Happy response.
Error object.
PUT /api/v1/environments/{env_name}/kafka-connections/{conn_name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91
{
"display_name": "text",
"description": "text",
"override_broker_addresses": [
"text"
],
"auth": {}
}{
"name": "text",
"display_name": "text",
"lrn": "text",
"description": "text",
"created_at": "2025-11-15T12:51:44.793Z",
"override_broker_addresses": [
"text"
],
"auth": {}
}Deletes a particular Environment's Kafka connection.
The bearer token can be obtained by creating a ServiceAccount.
Succesful deletion.
Error object.
DELETE /api/v1/environments/{env_name}/kafka-connections/{conn_name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Generates a new agent key and invalidates the old.
The bearer token can be obtained by creating a ServiceAccount.
Happy response.
Is returned on creation, contains the agent key but lacks dynamic fields which are unavailble on creation by definition.
Error object.
POST /api/v1/environments/{name}/renew-key HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-11-15T12:51:44.793Z",
"tier": "development",
"status": {
"agent_connected": true,
"agent": {
"updated_at": "2025-11-15T12:51:44.793Z",
"roundtrip_duration": 1,
"agent": {
"hostname": "text",
"version": "text",
"protocol_version": "text",
"capabilities": {
"metrics": true,
"k2k": true,
"publish": true
}
},
"metrics": {
"kafka": {
"version": "text",
"num_brokers": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"data": {
"num_topics": 1,
"num_partitions": 1,
"num_schemas": 1,
"num_policies": 1,
"topic_data_total_bytes": 1,
"data_in_bytes_per_sec": 1,
"data_out_bytes_per_sec": 1,
"data_in_messages_per_sec": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"apps": {
"num_consumers": 1,
"num_other_apps": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"connect": {
"num_clusters": 1,
"num_connectors": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
},
"other": {
"num_issues": 1,
"updated_at": "2025-11-15T12:51:44.793Z"
}
}
}
},
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"agent_key": "text"
}Provides Server-Sent Events (SSE) for environment updates. TODO.
The bearer token can be obtained by creating a ServiceAccount.
Error object.
GET /api/v1/environments/live/sse HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Error object.
{
"type": "not_found",
"title": "text",
"status": 1,
"invalid_fields": [
{
"name": "text",
"error": "reference_not_found",
"title": "text"
}
],
"sso_url": "text",
"request_id": "text"
}Server-Sent Events (SSE) stream of environment list changes. Wire format follows MDN SSE with named events: the JSON payload is carried in the data field and the event name is written in a preceding event field. Auth is applied per-item before emission. The server emits the following named events: initial (full current list, EnvironmentLiveItemsPayload), upsert (only changed or created environments, EnvironmentLiveItemsPayload), and delete (only deleted environment IDs, EnvironmentLiveDeletePayload).
The bearer token can be obtained by creating a ServiceAccount.
Error object.
GET /api/v2/environments/live/sse HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Error object.
{
"type": "not_found",
"title": "text",
"status": 1,
"invalid_fields": [
{
"name": "text",
"error": "reference_not_found",
"title": "text"
}
],
"sso_url": "text",
"request_id": "text"
}Proxies HTTP to a Lenses instance. Note: this is not a regular HTTP API endpoint. The path specified here is a prefix. Everything beneath it gets proxied to the corresponding Lenses instance. Any request body and method (the GET here is only a placeholder) are accepted, as long as the Lenses API accepts it. The connection can even be upgraded to a websocket. The status code and response body are controlled by the Lenses API. This concept does not fit into the OpenAPI world at all; this definition is only here for the sake of documentation to avoid having an undocumented dark matter API.
The bearer token can be obtained by creating a ServiceAccount.
Error object.
GET /api/v1/environments/{name}/proxy/ HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Error object.
{
"type": "not_found",
"title": "text",
"status": 1,
"invalid_fields": [
{
"name": "text",
"error": "reference_not_found",
"title": "text"
}
],
"sso_url": "text",
"request_id": "text"
}Last updated
Was this helpful?