Environments

Manage Lenses environments and configurations

get

Lists all environments

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

200

Happy response.

application/json

Contains a list of Environments.

default

Error object.

application/json

get/api/v1/environments

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": "2026-01-01T00:00:00.000Z",
      "tier": "development",
      "status": {
        "agent_connected": true,
        "agent": {
          "updated_at": "2026-01-01T00:00:00.000Z",
          "connected_at": "2026-01-01T00:00:00.000Z",
          "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": "2026-01-01T00:00:00.000Z"
            },
            "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": "2026-01-01T00:00:00.000Z"
            },
            "apps": {
              "num_consumers": 1,
              "num_other_apps": 1,
              "updated_at": "2026-01-01T00:00:00.000Z"
            },
            "connect": {
              "num_clusters": 1,
              "num_connectors": 1,
              "updated_at": "2026-01-01T00:00:00.000Z"
            },
            "other": {
              "num_issues": 1,
              "updated_at": "2026-01-01T00:00:00.000Z"
            }
          }
        }
      },
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

post

Creates a new environment.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Body

namestring · hq-resource-name · min: 1 · max: 63Required

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.

display_namestring · min: 1 · max: 150Optional

Sets the display name of the new environment. If not provided, the value of "name" will be used.

tierstring · enumRequired

Enumerates Tiers.

Possible values:

Responses

201

Happy response.

application/json

Represents a Lenses Instance, somewhere.

namestringRequired

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

tierstring · enumRequired

Enumerates Tiers.

Possible values:

agent_keystringRequired

default

Error object.

application/json

post/api/v1/environments

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": "2026-01-01T00:00:00.000Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2026-01-01T00:00:00.000Z",
      "connected_at": "2026-01-01T00:00:00.000Z",
      "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": "2026-01-01T00:00:00.000Z"
        },
        "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": "2026-01-01T00:00:00.000Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "agent_key": "text"
}

get

Retrieves a single environment by name.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

200

Happy response.

application/json

Represents a Lenses Instance, somewhere.

namestringRequired

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

tierstring · enumRequired

Enumerates Tiers.

Possible values:

default

Error object.

application/json

get/api/v1/environments/{name}

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": "2026-01-01T00:00:00.000Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2026-01-01T00:00:00.000Z",
      "connected_at": "2026-01-01T00:00:00.000Z",
      "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": "2026-01-01T00:00:00.000Z"
        },
        "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": "2026-01-01T00:00:00.000Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

delete

Deletes an environment.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

204

Successful deletion.

No content

default

Error object.

application/json

delete/api/v1/environments/{name}

DELETE /api/v1/environments/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

patch

Updates an environment.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

tierstring · enumOptional

Enumerates Tiers.

Possible values:

display_namestring · min: 1 · max: 150Optional

Updates the display name of the environment.

Responses

200

Happy response.

application/json

Represents a Lenses Instance, somewhere.

namestringRequired

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

tierstring · enumRequired

Enumerates Tiers.

Possible values:

default

Error object.

application/json

patch/api/v1/environments/{name}

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": "2026-01-01T00:00:00.000Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2026-01-01T00:00:00.000Z",
      "connected_at": "2026-01-01T00:00:00.000Z",
      "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": "2026-01-01T00:00:00.000Z"
        },
        "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": "2026-01-01T00:00:00.000Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

get

Lists Kafka connections defined for an Environment.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

env_namestringRequired

Responses

200

Happy response.

application/json

Contains a list of KafkaConnections.

default

Error object.

application/json

get/api/v1/environments/{env_name}/kafka-connections

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": "2026-01-01T00:00:00.000Z",
      "override_broker_addresses": [
        "text"
      ],
      "auth": {}
    }
  ]
}

get

Retrieves a Kafka connection defined for an Environment.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

env_namestringRequired

conn_namestringRequired

Responses

200

Happy response.

application/json

Defines Kafka connection settings for applications.

namestring · hq-resource-nameRequired

Uniquely identifies a connection within an environment.

display_namestring · max: 150Required

lrnstringRequired

Contains the resource identifier.

descriptionstring · max: 280Required

Has the description of the object.

created_atstring · date-timeRequired

override_broker_addressesstring[]Optional

Optionally overrides the broker addresses. If not set, those of the agent are used.

authone ofRequired

Contains auth settings specific to a particular auth type.

object · hq_KafkaConnectionAuthSettingsPlaintextOptional

Configures Kafka Plaintext "authentication".

or

or

or

default

Error object.

application/json

get/api/v1/environments/{env_name}/kafka-connections/{conn_name}

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": "2026-01-01T00:00:00.000Z",
  "override_broker_addresses": [
    "text"
  ],
  "auth": {}
}

put

Upserts a particular Environment's Kafka connection.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

env_namestringRequired

conn_namestringRequired

Body

Creates/updates a Kafka connection.

display_namestring · max: 150Optional

Sets the display name of the new KafkaConnection. If not provided, the value of "name" will be used.

descriptionstring · max: 280Optional

Has the optional description of the object.

override_broker_addressesstring[]Optional

Optionally overrides the broker addresses. If not set, those of the agent are used.

authone ofRequired

Contains auth settings specific to a particular auth type.

object · hq_KafkaConnectionAuthSettingsPlaintextOptional

Configures Kafka Plaintext "authentication".

or

or

or

Responses

200

Happy response.

application/json

Defines Kafka connection settings for applications.

namestring · hq-resource-nameRequired

Uniquely identifies a connection within an environment.

display_namestring · max: 150Required

lrnstringRequired

Contains the resource identifier.

descriptionstring · max: 280Required

Has the description of the object.

created_atstring · date-timeRequired

override_broker_addressesstring[]Optional

Optionally overrides the broker addresses. If not set, those of the agent are used.

authone ofRequired

Contains auth settings specific to a particular auth type.

object · hq_KafkaConnectionAuthSettingsPlaintextOptional

Configures Kafka Plaintext "authentication".

or

or

or

default

Error object.

application/json

put/api/v1/environments/{env_name}/kafka-connections/{conn_name}

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": "2026-01-01T00:00:00.000Z",
  "override_broker_addresses": [
    "text"
  ],
  "auth": {}
}

delete

Deletes a particular Environment's Kafka connection.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

env_namestringRequired

conn_namestringRequired

Responses

204

Succesful deletion.

No content

default

Error object.

application/json

delete/api/v1/environments/{env_name}/kafka-connections/{conn_name}

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

post

Generates a new agent key and invalidates the old.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

200

Happy response.

application/json

Represents a Lenses Instance, somewhere.

namestringRequired

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

tierstring · enumRequired

Enumerates Tiers.

Possible values:

agent_keystringRequired

default

Error object.

application/json

post/api/v1/environments/{name}/renew-key

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": "2026-01-01T00:00:00.000Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2026-01-01T00:00:00.000Z",
      "connected_at": "2026-01-01T00:00:00.000Z",
      "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": "2026-01-01T00:00:00.000Z"
        },
        "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": "2026-01-01T00:00:00.000Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2026-01-01T00:00:00.000Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "agent_key": "text"
}

get

Provides Server-Sent Events (SSE) for environment updates. TODO.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

default

Error object.

application/json

Implements the RFC7807 "Problem Details", see https://www.rfc-editor.org/rfc/rfc7807.

typestring · enumOptional

Enumerates possible error types.

Possible values:

titlestringRequired

Describes the problem in a human readable fashion.

statusintegerRequired

Is a copy of the http status code.

sso_urlstringOptional

Contains in case of an "unauthorised" type of error, the url of the SSO provider, if any.

request_idstringOptional

Is set to the id of this request. Can be used to correlate backend logs.

get/api/v1/environments/live/sse

GET /api/v1/environments/live/sse HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

default

Error object.

{
  "type": "not_found",
  "title": "text",
  "status": 1,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text",
      "pointer": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}

get

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

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

default

Error object.

application/json

Implements the RFC7807 "Problem Details", see https://www.rfc-editor.org/rfc/rfc7807.

typestring · enumOptional

Enumerates possible error types.

Possible values:

titlestringRequired

Describes the problem in a human readable fashion.

statusintegerRequired

Is a copy of the http status code.

sso_urlstringOptional

Contains in case of an "unauthorised" type of error, the url of the SSO provider, if any.

request_idstringOptional

Is set to the id of this request. Can be used to correlate backend logs.

get/api/v2/environments/live/sse

GET /api/v2/environments/live/sse HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

default

Error object.

{
  "type": "not_found",
  "title": "text",
  "status": 1,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text",
      "pointer": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}

get

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.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

default

Error object.

application/json

Implements the RFC7807 "Problem Details", see https://www.rfc-editor.org/rfc/rfc7807.

typestring · enumOptional

Enumerates possible error types.

Possible values:

titlestringRequired

Describes the problem in a human readable fashion.

statusintegerRequired

Is a copy of the http status code.

sso_urlstringOptional

Contains in case of an "unauthorised" type of error, the url of the SSO provider, if any.

request_idstringOptional

Is set to the id of this request. Can be used to correlate backend logs.

get/api/v1/environments/{name}/proxy/

GET /api/v1/environments/{name}/proxy/ HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

default

Error object.

{
  "type": "not_found",
  "title": "text",
  "status": 1,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text",
      "pointer": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}