# Environments

Manage Lenses environments and configurations

## GET /api/v1/environments

> Lists all environments

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_EnvironmentList":{"type":"object","description":"Contains a list of Environments.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_Environment"}}},"required":["items"]},"hq_Environment":{"type":"object","description":"Represents a Lenses Instance, somewhere.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"tier":{"$ref":"#/components/schemas/hq_Tier"},"status":{"$ref":"#/components/schemas/hq_LiveEnvironmentInfo"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","tier","status"]},"hq_Tier":{"type":"string","description":"Enumerates Tiers.","enum":["development","staging","production"]},"hq_LiveEnvironmentInfo":{"type":"object","description":"Contains dynamic properties of the Agent, brought in via a connected\nagent. Only when the agent is connected to HQ, agent info can be\nupdated. An environment that never had a connected agent cannot have a\nLiveAgentInfo.\n","properties":{"agent_connected":{"type":"boolean","description":"Signals whether an agent is currently connected."},"agent":{"$ref":"#/components/schemas/hq_LiveAgentInfo","description":"Initialised on first agent connect, and updated only while connected."}},"required":["agent_connected"]},"hq_LiveAgentInfo":{"type":"object","description":"Is a collection of fields related to an agent. Updated only when an agent is connected.\n","properties":{"updated_at":{"format":"date-time","type":"string","description":"Contains the time instant this object as a whole was updated."},"connected_at":{"format":"date-time","type":"string","description":"Contains the time instant the agent connected to HQ."},"roundtrip_duration":{"type":"number","format":"double","description":"Is measured in seconds."},"agent":{"$ref":"#/components/schemas/hq_LensesAgentSummary"},"metrics":{"$ref":"#/components/schemas/hq_AgentMetrics"}},"required":["updated_at","roundtrip_duration","agent"]},"hq_LensesAgentSummary":{"type":"object","description":"Bundles information about the agent.","properties":{"hostname":{"type":"string","description":"Is set to the hostname of the machine the agent runs on."},"version":{"type":"string","description":"Contains the version of the agent executable."},"protocol_version":{"type":"string","description":"Contains the internal protocol version implemented by the agent."},"capabilities":{"$ref":"#/components/schemas/hq_AgentCapabilities"}},"required":["hostname","version","capabilities","protocol_version"]},"hq_AgentCapabilities":{"type":"object","description":"Exposes capabilities of this particular agent.","properties":{"metrics":{"type":"boolean","description":"Is set to true if the agent can provide metrics."},"k2k":{"type":"boolean","description":"Is set to true if the agent can do Kafka2kafka."},"publish":{"type":"boolean","description":"Is set to true if the agent can publish to Kafka."}},"required":["metrics","k2k","publish"]},"hq_AgentMetrics":{"type":"object","description":"Bundles several categories of agent metrics.","properties":{"kafka":{"$ref":"#/components/schemas/hq_AgentKafkaMetrics"},"data":{"$ref":"#/components/schemas/hq_AgentDataMetrics"},"apps":{"$ref":"#/components/schemas/hq_AgentAppsMetrics"},"connect":{"$ref":"#/components/schemas/hq_AgentConnectMetrics"},"other":{"$ref":"#/components/schemas/hq_AgentOtherMetrics"}},"required":[]},"hq_AgentKafkaMetrics":{"type":"object","description":"Is optionally part of AgentMetrics. Contains Kafka-specific metrics.\nUnavailable if Zoopeeker is not configured.\n","properties":{"version":{"type":"string"},"num_brokers":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["version","num_brokers","updated_at"]},"hq_AgentDataMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Data related metrics.","properties":{"num_topics":{"type":"integer"},"num_partitions":{"type":"integer"},"num_schemas":{"type":"integer"},"num_policies":{"type":"integer"},"topic_data_total_bytes":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Total size of all topic data including\nreplicas on disk [bytes].\n"},"data_in_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [bytes/s].\n"},"data_out_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data read from the brokers [bytes/s].\n"},"data_in_messages_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [msg/s].\n"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_topics","num_partitions","num_schemas","num_policies","updated_at"]},"hq_AgentAppsMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Apps metrics.","properties":{"num_consumers":{"type":"integer"},"num_other_apps":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_consumers","num_other_apps","updated_at"]},"hq_AgentConnectMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Kafka Connect metrics.","properties":{"num_clusters":{"type":"integer"},"num_connectors":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_clusters","num_connectors","updated_at"]},"hq_AgentOtherMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains miscellaneous metrics.","properties":{"num_issues":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_issues","updated_at"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments":{"get":{"description":"Lists all environments","operationId":"listEnvironments","responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_EnvironmentList"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## POST /api/v1/environments

> Creates a new environment.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_CreateEnvironmentRequest":{"type":"object","properties":{"name":{"type":"string","format":"hq-resource-name","description":"Sets the name of the new environment. It must be a valid HQ resource\nname: it can only contain lowercase alphanumeric characters or\nhyphens; hyphens cannot appear at the end or start; the length is 63\ncharacters at most.\n","minLength":1,"maxLength":63},"display_name":{"type":"string","description":"Sets the display name of the new environment. If not provided, the\nvalue of \"name\" will be used.\n","minLength":1,"maxLength":150},"tier":{"$ref":"#/components/schemas/hq_Tier"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","tier"]},"hq_Tier":{"type":"string","description":"Enumerates Tiers.","enum":["development","staging","production"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_NewEnvironmentWithKey":{"description":"Is returned on creation, contains the agent key but lacks dynamic fields which are unavailble on creation by definition.","allOf":[{"$ref":"#/components/schemas/hq_Environment"},{"type":"object","properties":{"agent_key":{"type":"string"}},"required":["agent_key"]}]},"hq_Environment":{"type":"object","description":"Represents a Lenses Instance, somewhere.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"tier":{"$ref":"#/components/schemas/hq_Tier"},"status":{"$ref":"#/components/schemas/hq_LiveEnvironmentInfo"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","tier","status"]},"hq_LiveEnvironmentInfo":{"type":"object","description":"Contains dynamic properties of the Agent, brought in via a connected\nagent. Only when the agent is connected to HQ, agent info can be\nupdated. An environment that never had a connected agent cannot have a\nLiveAgentInfo.\n","properties":{"agent_connected":{"type":"boolean","description":"Signals whether an agent is currently connected."},"agent":{"$ref":"#/components/schemas/hq_LiveAgentInfo","description":"Initialised on first agent connect, and updated only while connected."}},"required":["agent_connected"]},"hq_LiveAgentInfo":{"type":"object","description":"Is a collection of fields related to an agent. Updated only when an agent is connected.\n","properties":{"updated_at":{"format":"date-time","type":"string","description":"Contains the time instant this object as a whole was updated."},"connected_at":{"format":"date-time","type":"string","description":"Contains the time instant the agent connected to HQ."},"roundtrip_duration":{"type":"number","format":"double","description":"Is measured in seconds."},"agent":{"$ref":"#/components/schemas/hq_LensesAgentSummary"},"metrics":{"$ref":"#/components/schemas/hq_AgentMetrics"}},"required":["updated_at","roundtrip_duration","agent"]},"hq_LensesAgentSummary":{"type":"object","description":"Bundles information about the agent.","properties":{"hostname":{"type":"string","description":"Is set to the hostname of the machine the agent runs on."},"version":{"type":"string","description":"Contains the version of the agent executable."},"protocol_version":{"type":"string","description":"Contains the internal protocol version implemented by the agent."},"capabilities":{"$ref":"#/components/schemas/hq_AgentCapabilities"}},"required":["hostname","version","capabilities","protocol_version"]},"hq_AgentCapabilities":{"type":"object","description":"Exposes capabilities of this particular agent.","properties":{"metrics":{"type":"boolean","description":"Is set to true if the agent can provide metrics."},"k2k":{"type":"boolean","description":"Is set to true if the agent can do Kafka2kafka."},"publish":{"type":"boolean","description":"Is set to true if the agent can publish to Kafka."}},"required":["metrics","k2k","publish"]},"hq_AgentMetrics":{"type":"object","description":"Bundles several categories of agent metrics.","properties":{"kafka":{"$ref":"#/components/schemas/hq_AgentKafkaMetrics"},"data":{"$ref":"#/components/schemas/hq_AgentDataMetrics"},"apps":{"$ref":"#/components/schemas/hq_AgentAppsMetrics"},"connect":{"$ref":"#/components/schemas/hq_AgentConnectMetrics"},"other":{"$ref":"#/components/schemas/hq_AgentOtherMetrics"}},"required":[]},"hq_AgentKafkaMetrics":{"type":"object","description":"Is optionally part of AgentMetrics. Contains Kafka-specific metrics.\nUnavailable if Zoopeeker is not configured.\n","properties":{"version":{"type":"string"},"num_brokers":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["version","num_brokers","updated_at"]},"hq_AgentDataMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Data related metrics.","properties":{"num_topics":{"type":"integer"},"num_partitions":{"type":"integer"},"num_schemas":{"type":"integer"},"num_policies":{"type":"integer"},"topic_data_total_bytes":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Total size of all topic data including\nreplicas on disk [bytes].\n"},"data_in_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [bytes/s].\n"},"data_out_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data read from the brokers [bytes/s].\n"},"data_in_messages_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [msg/s].\n"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_topics","num_partitions","num_schemas","num_policies","updated_at"]},"hq_AgentAppsMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Apps metrics.","properties":{"num_consumers":{"type":"integer"},"num_other_apps":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_consumers","num_other_apps","updated_at"]},"hq_AgentConnectMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Kafka Connect metrics.","properties":{"num_clusters":{"type":"integer"},"num_connectors":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_clusters","num_connectors","updated_at"]},"hq_AgentOtherMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains miscellaneous metrics.","properties":{"num_issues":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_issues","updated_at"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments":{"post":{"description":"Creates a new environment.","operationId":"createEnvironment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_CreateEnvironmentRequest"}}}},"responses":{"201":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_NewEnvironmentWithKey"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## GET /api/v1/environments/{name}

> Retrieves a single environment by name.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Environment":{"type":"object","description":"Represents a Lenses Instance, somewhere.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"tier":{"$ref":"#/components/schemas/hq_Tier"},"status":{"$ref":"#/components/schemas/hq_LiveEnvironmentInfo"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","tier","status"]},"hq_Tier":{"type":"string","description":"Enumerates Tiers.","enum":["development","staging","production"]},"hq_LiveEnvironmentInfo":{"type":"object","description":"Contains dynamic properties of the Agent, brought in via a connected\nagent. Only when the agent is connected to HQ, agent info can be\nupdated. An environment that never had a connected agent cannot have a\nLiveAgentInfo.\n","properties":{"agent_connected":{"type":"boolean","description":"Signals whether an agent is currently connected."},"agent":{"$ref":"#/components/schemas/hq_LiveAgentInfo","description":"Initialised on first agent connect, and updated only while connected."}},"required":["agent_connected"]},"hq_LiveAgentInfo":{"type":"object","description":"Is a collection of fields related to an agent. Updated only when an agent is connected.\n","properties":{"updated_at":{"format":"date-time","type":"string","description":"Contains the time instant this object as a whole was updated."},"connected_at":{"format":"date-time","type":"string","description":"Contains the time instant the agent connected to HQ."},"roundtrip_duration":{"type":"number","format":"double","description":"Is measured in seconds."},"agent":{"$ref":"#/components/schemas/hq_LensesAgentSummary"},"metrics":{"$ref":"#/components/schemas/hq_AgentMetrics"}},"required":["updated_at","roundtrip_duration","agent"]},"hq_LensesAgentSummary":{"type":"object","description":"Bundles information about the agent.","properties":{"hostname":{"type":"string","description":"Is set to the hostname of the machine the agent runs on."},"version":{"type":"string","description":"Contains the version of the agent executable."},"protocol_version":{"type":"string","description":"Contains the internal protocol version implemented by the agent."},"capabilities":{"$ref":"#/components/schemas/hq_AgentCapabilities"}},"required":["hostname","version","capabilities","protocol_version"]},"hq_AgentCapabilities":{"type":"object","description":"Exposes capabilities of this particular agent.","properties":{"metrics":{"type":"boolean","description":"Is set to true if the agent can provide metrics."},"k2k":{"type":"boolean","description":"Is set to true if the agent can do Kafka2kafka."},"publish":{"type":"boolean","description":"Is set to true if the agent can publish to Kafka."}},"required":["metrics","k2k","publish"]},"hq_AgentMetrics":{"type":"object","description":"Bundles several categories of agent metrics.","properties":{"kafka":{"$ref":"#/components/schemas/hq_AgentKafkaMetrics"},"data":{"$ref":"#/components/schemas/hq_AgentDataMetrics"},"apps":{"$ref":"#/components/schemas/hq_AgentAppsMetrics"},"connect":{"$ref":"#/components/schemas/hq_AgentConnectMetrics"},"other":{"$ref":"#/components/schemas/hq_AgentOtherMetrics"}},"required":[]},"hq_AgentKafkaMetrics":{"type":"object","description":"Is optionally part of AgentMetrics. Contains Kafka-specific metrics.\nUnavailable if Zoopeeker is not configured.\n","properties":{"version":{"type":"string"},"num_brokers":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["version","num_brokers","updated_at"]},"hq_AgentDataMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Data related metrics.","properties":{"num_topics":{"type":"integer"},"num_partitions":{"type":"integer"},"num_schemas":{"type":"integer"},"num_policies":{"type":"integer"},"topic_data_total_bytes":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Total size of all topic data including\nreplicas on disk [bytes].\n"},"data_in_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [bytes/s].\n"},"data_out_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data read from the brokers [bytes/s].\n"},"data_in_messages_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [msg/s].\n"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_topics","num_partitions","num_schemas","num_policies","updated_at"]},"hq_AgentAppsMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Apps metrics.","properties":{"num_consumers":{"type":"integer"},"num_other_apps":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_consumers","num_other_apps","updated_at"]},"hq_AgentConnectMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Kafka Connect metrics.","properties":{"num_clusters":{"type":"integer"},"num_connectors":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_clusters","num_connectors","updated_at"]},"hq_AgentOtherMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains miscellaneous metrics.","properties":{"num_issues":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_issues","updated_at"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{name}":{"get":{"description":"Retrieves a single environment by name.","operationId":"getEnvironment","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Environment"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## DELETE /api/v1/environments/{name}

> Deletes an environment.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{name}":{"delete":{"description":"Deletes an environment.","operationId":"deleteEnvironment","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Successful deletion."},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## PATCH /api/v1/environments/{name}

> Updates an environment.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_UpdateEnvironmentRequest":{"type":"object","properties":{"tier":{"$ref":"#/components/schemas/hq_Tier"},"metadata":{"$ref":"#/components/schemas/hq_MetadataPatchRequest"},"display_name":{"type":"string","description":"Updates the display name of the environment.","minLength":1,"maxLength":150}}},"hq_Tier":{"type":"string","description":"Enumerates Tiers.","enum":["development","staging","production"]},"hq_MetadataPatchRequest":{"type":"object","description":"Patches metadata. It has the following semantics:\n  - Absent keys are left untouched;\n  - Null values are deleted;\n  - Non-null values are replaced.\n","additionalProperties":{"type":"string","nullable":true}},"hq_Environment":{"type":"object","description":"Represents a Lenses Instance, somewhere.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"tier":{"$ref":"#/components/schemas/hq_Tier"},"status":{"$ref":"#/components/schemas/hq_LiveEnvironmentInfo"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","tier","status"]},"hq_LiveEnvironmentInfo":{"type":"object","description":"Contains dynamic properties of the Agent, brought in via a connected\nagent. Only when the agent is connected to HQ, agent info can be\nupdated. An environment that never had a connected agent cannot have a\nLiveAgentInfo.\n","properties":{"agent_connected":{"type":"boolean","description":"Signals whether an agent is currently connected."},"agent":{"$ref":"#/components/schemas/hq_LiveAgentInfo","description":"Initialised on first agent connect, and updated only while connected."}},"required":["agent_connected"]},"hq_LiveAgentInfo":{"type":"object","description":"Is a collection of fields related to an agent. Updated only when an agent is connected.\n","properties":{"updated_at":{"format":"date-time","type":"string","description":"Contains the time instant this object as a whole was updated."},"connected_at":{"format":"date-time","type":"string","description":"Contains the time instant the agent connected to HQ."},"roundtrip_duration":{"type":"number","format":"double","description":"Is measured in seconds."},"agent":{"$ref":"#/components/schemas/hq_LensesAgentSummary"},"metrics":{"$ref":"#/components/schemas/hq_AgentMetrics"}},"required":["updated_at","roundtrip_duration","agent"]},"hq_LensesAgentSummary":{"type":"object","description":"Bundles information about the agent.","properties":{"hostname":{"type":"string","description":"Is set to the hostname of the machine the agent runs on."},"version":{"type":"string","description":"Contains the version of the agent executable."},"protocol_version":{"type":"string","description":"Contains the internal protocol version implemented by the agent."},"capabilities":{"$ref":"#/components/schemas/hq_AgentCapabilities"}},"required":["hostname","version","capabilities","protocol_version"]},"hq_AgentCapabilities":{"type":"object","description":"Exposes capabilities of this particular agent.","properties":{"metrics":{"type":"boolean","description":"Is set to true if the agent can provide metrics."},"k2k":{"type":"boolean","description":"Is set to true if the agent can do Kafka2kafka."},"publish":{"type":"boolean","description":"Is set to true if the agent can publish to Kafka."}},"required":["metrics","k2k","publish"]},"hq_AgentMetrics":{"type":"object","description":"Bundles several categories of agent metrics.","properties":{"kafka":{"$ref":"#/components/schemas/hq_AgentKafkaMetrics"},"data":{"$ref":"#/components/schemas/hq_AgentDataMetrics"},"apps":{"$ref":"#/components/schemas/hq_AgentAppsMetrics"},"connect":{"$ref":"#/components/schemas/hq_AgentConnectMetrics"},"other":{"$ref":"#/components/schemas/hq_AgentOtherMetrics"}},"required":[]},"hq_AgentKafkaMetrics":{"type":"object","description":"Is optionally part of AgentMetrics. Contains Kafka-specific metrics.\nUnavailable if Zoopeeker is not configured.\n","properties":{"version":{"type":"string"},"num_brokers":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["version","num_brokers","updated_at"]},"hq_AgentDataMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Data related metrics.","properties":{"num_topics":{"type":"integer"},"num_partitions":{"type":"integer"},"num_schemas":{"type":"integer"},"num_policies":{"type":"integer"},"topic_data_total_bytes":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Total size of all topic data including\nreplicas on disk [bytes].\n"},"data_in_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [bytes/s].\n"},"data_out_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data read from the brokers [bytes/s].\n"},"data_in_messages_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [msg/s].\n"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_topics","num_partitions","num_schemas","num_policies","updated_at"]},"hq_AgentAppsMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Apps metrics.","properties":{"num_consumers":{"type":"integer"},"num_other_apps":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_consumers","num_other_apps","updated_at"]},"hq_AgentConnectMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Kafka Connect metrics.","properties":{"num_clusters":{"type":"integer"},"num_connectors":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_clusters","num_connectors","updated_at"]},"hq_AgentOtherMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains miscellaneous metrics.","properties":{"num_issues":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_issues","updated_at"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{name}":{"patch":{"description":"Updates an environment.","operationId":"updateEnvironment","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_UpdateEnvironmentRequest"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Environment"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## GET /api/v1/environments/{env\_name}/kafka-connections

> Lists Kafka connections defined for an Environment.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_KafkaConnectionList":{"type":"object","description":"Contains a list of KafkaConnections.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_KafkaConnection"}}},"required":["items"]},"hq_KafkaConnection":{"description":"Defines Kafka connection settings for applications.","type":"object","properties":{"name":{"type":"string","format":"hq-resource-name","description":"Uniquely identifies a connection within an environment."},"display_name":{"type":"string","maxLength":150},"lrn":{"type":"string","description":"Contains the resource identifier."},"description":{"type":"string","description":"Has the description of the object.","maxLength":280},"created_at":{"format":"date-time","type":"string"},"override_broker_addresses":{"description":"Optionally overrides the broker addresses. If not set, those of the agent are used.","type":"array","items":{"type":"string"}},"auth":{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettings"}},"required":["name","display_name","description","created_at","lrn","auth"]},"hq_KafkaConnectionAuthSettings":{"description":"Contains auth settings specific to a particular auth type.","oneOf":[{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsPlaintext"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsAWSIAM"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsMTLS"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsSASLSSL"}],"discriminator":{"propertyName":"type","mapping":{"plaintext":"#/components/schemas/hq_KafkaConnectionAuthSettingsPlaintext","aws_iam":"#/components/schemas/hq_KafkaConnectionAuthSettingsAWSIAM","mtls":"#/components/schemas/hq_KafkaConnectionAuthSettingsMTLS","sasl_ssl":"#/components/schemas/hq_KafkaConnectionAuthSettingsSASLSSL"}}},"hq_KafkaConnectionAuthSettingsPlaintext":{"type":"object","description":"Configures Kafka Plaintext \"authentication\".","required":[]},"hq_KafkaConnectionAuthSettingsAWSIAM":{"type":"object","description":"Configures Kafka AWS IAM authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"service_account":{"type":"string","description":"Holds the Kubernetes service account name for IRSA.","format":"K8sDns1123Subdomain"}},"required":["kubernetes_namespace_lrn","service_account"]},"hq_KafkaConnectionAuthSettingsMTLS":{"type":"object","description":"Configures Kafka mTLS authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"keystore":{"$ref":"#/components/schemas/hq_K8sKeystoreRef"},"truststore":{"$ref":"#/components/schemas/hq_K8sTruststoreRef"}},"required":["kubernetes_namespace_lrn","keystore","truststore"]},"hq_K8sKeystoreRef":{"description":"References Kubernetes secrets for a keystore in either PEM or PKCS12\nencoding.\n","oneOf":[{"$ref":"#/components/schemas/hq_K8sPKCS12KeystoreRef"},{"$ref":"#/components/schemas/hq_K8sPEMKeystoreRef"}],"discriminator":{"propertyName":"type","mapping":{"pkcs12":"#/components/schemas/hq_K8sPKCS12KeystoreRef","pem":"#/components/schemas/hq_K8sPEMKeystoreRef"}}},"hq_K8sPKCS12KeystoreRef":{"type":"object","description":"References Kubernetes secrets for a keystore: the store itself in PKCS12\nencoding and its password. For Strimzi, the secret name would be the\nsame as the corresponding Kafka user (kafkausers.kafka.strimzi.io CRD),\nwith key \"user.p12\" the store and key \"user.password\" the store's\npassword.\n","properties":{"store":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["store","password"]},"hq_KubernetesSecretKeyReference":{"type":"object","description":"Contains a reference to a particular key within a Kubernetes secret. The\nnamespace is expected to be defined elsewhere.\n","properties":{"secret_name":{"type":"string","description":"Holds the Kubernetes Secret's name.","format":"K8sDns1123Subdomain"},"secret_key":{"type":"string","description":"Has the name of the key within the Kubernetes Secret.","format":"K8sSecretKey"}},"required":["secret_name","secret_key"]},"hq_K8sPEMKeystoreRef":{"type":"object","description":"References Kubernetes secrets for a \"keystore\" in PEM encoding: a public\ncertificate and a private key. For Strimzi, the secret name would be the\nsame as the corresponding Kafka user (kafkausers.kafka.strimzi.io CRD),\nwith key \"user.crt\" the cert and key \"user.key\" the key.\n","properties":{"cert":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"key":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["cert","key"]},"hq_K8sTruststoreRef":{"description":"References Kubernetes secrets for a truststore in either PEM or PKCS12\nencoding.\n","oneOf":[{"$ref":"#/components/schemas/hq_K8sPKCS12TruststoreRef"},{"$ref":"#/components/schemas/hq_K8sPEMTruststoreRef"}],"discriminator":{"propertyName":"type","mapping":{"pkcs12":"#/components/schemas/hq_K8sPKCS12TruststoreRef","pem":"#/components/schemas/hq_K8sPEMTruststoreRef"}}},"hq_K8sPKCS12TruststoreRef":{"type":"object","description":"References Kubernetes secrets for a truststore: the store itself in\nPKCS12 encoding and its password. For Strimzi, the secret name would\nhave the form of \"<cluster-name>-cluster-ca-cert\", with key \"ca.p12\" the\nstore and key \"ca.password\" the password.\n","properties":{"store":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["store","password"]},"hq_K8sPEMTruststoreRef":{"description":"References a Kubernetes secret for a \"truststore\" in PEM encoding which\ncomes down to one or more certificates. For Strimzi, the secret name\nwould have the form of \"<cluster-name>-cluster-ca-cert\", with key\n\"ca.crt\" the \"truststore\" itself.\n","allOf":[{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},{"type":"object","properties":{}}]},"hq_KafkaConnectionAuthSettingsSASLSSL":{"type":"object","description":"Configures Kafka SASL authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"mechanism":{"$ref":"#/components/schemas/hq_SASLMechanism"},"credentials":{"$ref":"#/components/schemas/hq_KafkaConnectionSASLCredentials"},"truststore":{"$ref":"#/components/schemas/hq_K8sTruststoreRef"}},"required":["kubernetes_namespace_lrn","mechanism","credentials","truststore"]},"hq_SASLMechanism":{"type":"string","description":"Enumerates supported SASL mechanisms.","enum":["plain","scram_sha_256","scram_sha_512"]},"hq_KafkaConnectionSASLCredentials":{"oneOf":[{"$ref":"#/components/schemas/hq_KafkaConnectionSASLUsernamePasswordRef"},{"$ref":"#/components/schemas/hq_KafkaConnectionSASLJAASConfigRef"}],"discriminator":{"propertyName":"type","mapping":{"username_password":"#/components/schemas/hq_KafkaConnectionSASLUsernamePasswordRef","jaas_config":"#/components/schemas/hq_KafkaConnectionSASLJAASConfigRef"}}},"hq_KafkaConnectionSASLUsernamePasswordRef":{"type":"object","properties":{"username":{"type":"string","minLength":1},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["username","password"]},"hq_KafkaConnectionSASLJAASConfigRef":{"allOf":[{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},{"type":"object","properties":{}}]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{env_name}/kafka-connections":{"get":{"description":"Lists Kafka connections defined for an Environment.","operationId":"listKafkaConnections","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_KafkaConnectionList"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## GET /api/v1/environments/{env\_name}/kafka-connections/{conn\_name}

> Retrieves a Kafka connection defined for an Environment.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_KafkaConnection":{"description":"Defines Kafka connection settings for applications.","type":"object","properties":{"name":{"type":"string","format":"hq-resource-name","description":"Uniquely identifies a connection within an environment."},"display_name":{"type":"string","maxLength":150},"lrn":{"type":"string","description":"Contains the resource identifier."},"description":{"type":"string","description":"Has the description of the object.","maxLength":280},"created_at":{"format":"date-time","type":"string"},"override_broker_addresses":{"description":"Optionally overrides the broker addresses. If not set, those of the agent are used.","type":"array","items":{"type":"string"}},"auth":{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettings"}},"required":["name","display_name","description","created_at","lrn","auth"]},"hq_KafkaConnectionAuthSettings":{"description":"Contains auth settings specific to a particular auth type.","oneOf":[{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsPlaintext"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsAWSIAM"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsMTLS"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsSASLSSL"}],"discriminator":{"propertyName":"type","mapping":{"plaintext":"#/components/schemas/hq_KafkaConnectionAuthSettingsPlaintext","aws_iam":"#/components/schemas/hq_KafkaConnectionAuthSettingsAWSIAM","mtls":"#/components/schemas/hq_KafkaConnectionAuthSettingsMTLS","sasl_ssl":"#/components/schemas/hq_KafkaConnectionAuthSettingsSASLSSL"}}},"hq_KafkaConnectionAuthSettingsPlaintext":{"type":"object","description":"Configures Kafka Plaintext \"authentication\".","required":[]},"hq_KafkaConnectionAuthSettingsAWSIAM":{"type":"object","description":"Configures Kafka AWS IAM authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"service_account":{"type":"string","description":"Holds the Kubernetes service account name for IRSA.","format":"K8sDns1123Subdomain"}},"required":["kubernetes_namespace_lrn","service_account"]},"hq_KafkaConnectionAuthSettingsMTLS":{"type":"object","description":"Configures Kafka mTLS authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"keystore":{"$ref":"#/components/schemas/hq_K8sKeystoreRef"},"truststore":{"$ref":"#/components/schemas/hq_K8sTruststoreRef"}},"required":["kubernetes_namespace_lrn","keystore","truststore"]},"hq_K8sKeystoreRef":{"description":"References Kubernetes secrets for a keystore in either PEM or PKCS12\nencoding.\n","oneOf":[{"$ref":"#/components/schemas/hq_K8sPKCS12KeystoreRef"},{"$ref":"#/components/schemas/hq_K8sPEMKeystoreRef"}],"discriminator":{"propertyName":"type","mapping":{"pkcs12":"#/components/schemas/hq_K8sPKCS12KeystoreRef","pem":"#/components/schemas/hq_K8sPEMKeystoreRef"}}},"hq_K8sPKCS12KeystoreRef":{"type":"object","description":"References Kubernetes secrets for a keystore: the store itself in PKCS12\nencoding and its password. For Strimzi, the secret name would be the\nsame as the corresponding Kafka user (kafkausers.kafka.strimzi.io CRD),\nwith key \"user.p12\" the store and key \"user.password\" the store's\npassword.\n","properties":{"store":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["store","password"]},"hq_KubernetesSecretKeyReference":{"type":"object","description":"Contains a reference to a particular key within a Kubernetes secret. The\nnamespace is expected to be defined elsewhere.\n","properties":{"secret_name":{"type":"string","description":"Holds the Kubernetes Secret's name.","format":"K8sDns1123Subdomain"},"secret_key":{"type":"string","description":"Has the name of the key within the Kubernetes Secret.","format":"K8sSecretKey"}},"required":["secret_name","secret_key"]},"hq_K8sPEMKeystoreRef":{"type":"object","description":"References Kubernetes secrets for a \"keystore\" in PEM encoding: a public\ncertificate and a private key. For Strimzi, the secret name would be the\nsame as the corresponding Kafka user (kafkausers.kafka.strimzi.io CRD),\nwith key \"user.crt\" the cert and key \"user.key\" the key.\n","properties":{"cert":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"key":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["cert","key"]},"hq_K8sTruststoreRef":{"description":"References Kubernetes secrets for a truststore in either PEM or PKCS12\nencoding.\n","oneOf":[{"$ref":"#/components/schemas/hq_K8sPKCS12TruststoreRef"},{"$ref":"#/components/schemas/hq_K8sPEMTruststoreRef"}],"discriminator":{"propertyName":"type","mapping":{"pkcs12":"#/components/schemas/hq_K8sPKCS12TruststoreRef","pem":"#/components/schemas/hq_K8sPEMTruststoreRef"}}},"hq_K8sPKCS12TruststoreRef":{"type":"object","description":"References Kubernetes secrets for a truststore: the store itself in\nPKCS12 encoding and its password. For Strimzi, the secret name would\nhave the form of \"<cluster-name>-cluster-ca-cert\", with key \"ca.p12\" the\nstore and key \"ca.password\" the password.\n","properties":{"store":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["store","password"]},"hq_K8sPEMTruststoreRef":{"description":"References a Kubernetes secret for a \"truststore\" in PEM encoding which\ncomes down to one or more certificates. For Strimzi, the secret name\nwould have the form of \"<cluster-name>-cluster-ca-cert\", with key\n\"ca.crt\" the \"truststore\" itself.\n","allOf":[{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},{"type":"object","properties":{}}]},"hq_KafkaConnectionAuthSettingsSASLSSL":{"type":"object","description":"Configures Kafka SASL authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"mechanism":{"$ref":"#/components/schemas/hq_SASLMechanism"},"credentials":{"$ref":"#/components/schemas/hq_KafkaConnectionSASLCredentials"},"truststore":{"$ref":"#/components/schemas/hq_K8sTruststoreRef"}},"required":["kubernetes_namespace_lrn","mechanism","credentials","truststore"]},"hq_SASLMechanism":{"type":"string","description":"Enumerates supported SASL mechanisms.","enum":["plain","scram_sha_256","scram_sha_512"]},"hq_KafkaConnectionSASLCredentials":{"oneOf":[{"$ref":"#/components/schemas/hq_KafkaConnectionSASLUsernamePasswordRef"},{"$ref":"#/components/schemas/hq_KafkaConnectionSASLJAASConfigRef"}],"discriminator":{"propertyName":"type","mapping":{"username_password":"#/components/schemas/hq_KafkaConnectionSASLUsernamePasswordRef","jaas_config":"#/components/schemas/hq_KafkaConnectionSASLJAASConfigRef"}}},"hq_KafkaConnectionSASLUsernamePasswordRef":{"type":"object","properties":{"username":{"type":"string","minLength":1},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["username","password"]},"hq_KafkaConnectionSASLJAASConfigRef":{"allOf":[{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},{"type":"object","properties":{}}]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{env_name}/kafka-connections/{conn_name}":{"get":{"description":"Retrieves a Kafka connection defined for an Environment.","operationId":"getKafkaConnection","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}},{"in":"path","name":"conn_name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_KafkaConnection"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## PUT /api/v1/environments/{env\_name}/kafka-connections/{conn\_name}

> Upserts a particular Environment's Kafka connection.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_UpsertKafkaConnectionRequest":{"description":"Creates/updates a Kafka connection.","type":"object","properties":{"display_name":{"type":"string","maxLength":150,"description":"Sets the display name of the new KafkaConnection. If not provided,\nthe value of \"name\" will be used.\n"},"description":{"type":"string","description":"Has the optional description of the object.","maxLength":280},"override_broker_addresses":{"description":"Optionally overrides the broker addresses. If not set, those of the agent are used.","type":"array","items":{"type":"string"}},"auth":{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettings"}},"required":["auth"]},"hq_KafkaConnectionAuthSettings":{"description":"Contains auth settings specific to a particular auth type.","oneOf":[{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsPlaintext"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsAWSIAM"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsMTLS"},{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettingsSASLSSL"}],"discriminator":{"propertyName":"type","mapping":{"plaintext":"#/components/schemas/hq_KafkaConnectionAuthSettingsPlaintext","aws_iam":"#/components/schemas/hq_KafkaConnectionAuthSettingsAWSIAM","mtls":"#/components/schemas/hq_KafkaConnectionAuthSettingsMTLS","sasl_ssl":"#/components/schemas/hq_KafkaConnectionAuthSettingsSASLSSL"}}},"hq_KafkaConnectionAuthSettingsPlaintext":{"type":"object","description":"Configures Kafka Plaintext \"authentication\".","required":[]},"hq_KafkaConnectionAuthSettingsAWSIAM":{"type":"object","description":"Configures Kafka AWS IAM authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"service_account":{"type":"string","description":"Holds the Kubernetes service account name for IRSA.","format":"K8sDns1123Subdomain"}},"required":["kubernetes_namespace_lrn","service_account"]},"hq_KafkaConnectionAuthSettingsMTLS":{"type":"object","description":"Configures Kafka mTLS authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"keystore":{"$ref":"#/components/schemas/hq_K8sKeystoreRef"},"truststore":{"$ref":"#/components/schemas/hq_K8sTruststoreRef"}},"required":["kubernetes_namespace_lrn","keystore","truststore"]},"hq_K8sKeystoreRef":{"description":"References Kubernetes secrets for a keystore in either PEM or PKCS12\nencoding.\n","oneOf":[{"$ref":"#/components/schemas/hq_K8sPKCS12KeystoreRef"},{"$ref":"#/components/schemas/hq_K8sPEMKeystoreRef"}],"discriminator":{"propertyName":"type","mapping":{"pkcs12":"#/components/schemas/hq_K8sPKCS12KeystoreRef","pem":"#/components/schemas/hq_K8sPEMKeystoreRef"}}},"hq_K8sPKCS12KeystoreRef":{"type":"object","description":"References Kubernetes secrets for a keystore: the store itself in PKCS12\nencoding and its password. For Strimzi, the secret name would be the\nsame as the corresponding Kafka user (kafkausers.kafka.strimzi.io CRD),\nwith key \"user.p12\" the store and key \"user.password\" the store's\npassword.\n","properties":{"store":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["store","password"]},"hq_KubernetesSecretKeyReference":{"type":"object","description":"Contains a reference to a particular key within a Kubernetes secret. The\nnamespace is expected to be defined elsewhere.\n","properties":{"secret_name":{"type":"string","description":"Holds the Kubernetes Secret's name.","format":"K8sDns1123Subdomain"},"secret_key":{"type":"string","description":"Has the name of the key within the Kubernetes Secret.","format":"K8sSecretKey"}},"required":["secret_name","secret_key"]},"hq_K8sPEMKeystoreRef":{"type":"object","description":"References Kubernetes secrets for a \"keystore\" in PEM encoding: a public\ncertificate and a private key. For Strimzi, the secret name would be the\nsame as the corresponding Kafka user (kafkausers.kafka.strimzi.io CRD),\nwith key \"user.crt\" the cert and key \"user.key\" the key.\n","properties":{"cert":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"key":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["cert","key"]},"hq_K8sTruststoreRef":{"description":"References Kubernetes secrets for a truststore in either PEM or PKCS12\nencoding.\n","oneOf":[{"$ref":"#/components/schemas/hq_K8sPKCS12TruststoreRef"},{"$ref":"#/components/schemas/hq_K8sPEMTruststoreRef"}],"discriminator":{"propertyName":"type","mapping":{"pkcs12":"#/components/schemas/hq_K8sPKCS12TruststoreRef","pem":"#/components/schemas/hq_K8sPEMTruststoreRef"}}},"hq_K8sPKCS12TruststoreRef":{"type":"object","description":"References Kubernetes secrets for a truststore: the store itself in\nPKCS12 encoding and its password. For Strimzi, the secret name would\nhave the form of \"<cluster-name>-cluster-ca-cert\", with key \"ca.p12\" the\nstore and key \"ca.password\" the password.\n","properties":{"store":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["store","password"]},"hq_K8sPEMTruststoreRef":{"description":"References a Kubernetes secret for a \"truststore\" in PEM encoding which\ncomes down to one or more certificates. For Strimzi, the secret name\nwould have the form of \"<cluster-name>-cluster-ca-cert\", with key\n\"ca.crt\" the \"truststore\" itself.\n","allOf":[{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},{"type":"object","properties":{}}]},"hq_KafkaConnectionAuthSettingsSASLSSL":{"type":"object","description":"Configures Kafka SASL authentication.","properties":{"kubernetes_namespace_lrn":{"type":"string","format":"kubernetes-namespace-lrn","description":"Determines the Kubernetes deployment namespace to which those settings apply."},"mechanism":{"$ref":"#/components/schemas/hq_SASLMechanism"},"credentials":{"$ref":"#/components/schemas/hq_KafkaConnectionSASLCredentials"},"truststore":{"$ref":"#/components/schemas/hq_K8sTruststoreRef"}},"required":["kubernetes_namespace_lrn","mechanism","credentials","truststore"]},"hq_SASLMechanism":{"type":"string","description":"Enumerates supported SASL mechanisms.","enum":["plain","scram_sha_256","scram_sha_512"]},"hq_KafkaConnectionSASLCredentials":{"oneOf":[{"$ref":"#/components/schemas/hq_KafkaConnectionSASLUsernamePasswordRef"},{"$ref":"#/components/schemas/hq_KafkaConnectionSASLJAASConfigRef"}],"discriminator":{"propertyName":"type","mapping":{"username_password":"#/components/schemas/hq_KafkaConnectionSASLUsernamePasswordRef","jaas_config":"#/components/schemas/hq_KafkaConnectionSASLJAASConfigRef"}}},"hq_KafkaConnectionSASLUsernamePasswordRef":{"type":"object","properties":{"username":{"type":"string","minLength":1},"password":{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"}},"required":["username","password"]},"hq_KafkaConnectionSASLJAASConfigRef":{"allOf":[{"$ref":"#/components/schemas/hq_KubernetesSecretKeyReference"},{"type":"object","properties":{}}]},"hq_KafkaConnection":{"description":"Defines Kafka connection settings for applications.","type":"object","properties":{"name":{"type":"string","format":"hq-resource-name","description":"Uniquely identifies a connection within an environment."},"display_name":{"type":"string","maxLength":150},"lrn":{"type":"string","description":"Contains the resource identifier."},"description":{"type":"string","description":"Has the description of the object.","maxLength":280},"created_at":{"format":"date-time","type":"string"},"override_broker_addresses":{"description":"Optionally overrides the broker addresses. If not set, those of the agent are used.","type":"array","items":{"type":"string"}},"auth":{"$ref":"#/components/schemas/hq_KafkaConnectionAuthSettings"}},"required":["name","display_name","description","created_at","lrn","auth"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{env_name}/kafka-connections/{conn_name}":{"put":{"description":"Upserts a particular Environment's Kafka connection.","operationId":"upsertKafkaConnection","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}},{"in":"path","name":"conn_name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_UpsertKafkaConnectionRequest"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_KafkaConnection"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## DELETE /api/v1/environments/{env\_name}/kafka-connections/{conn\_name}

> Deletes a particular Environment's Kafka connection.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{env_name}/kafka-connections/{conn_name}":{"delete":{"description":"Deletes a particular Environment's Kafka connection.","operationId":"deleteKafkaConnection","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}},{"in":"path","name":"conn_name","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Succesful deletion."},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## POST /api/v1/environments/{name}/renew-key

> Generates a new agent key and invalidates the old.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_NewEnvironmentWithKey":{"description":"Is returned on creation, contains the agent key but lacks dynamic fields which are unavailble on creation by definition.","allOf":[{"$ref":"#/components/schemas/hq_Environment"},{"type":"object","properties":{"agent_key":{"type":"string"}},"required":["agent_key"]}]},"hq_Environment":{"type":"object","description":"Represents a Lenses Instance, somewhere.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"tier":{"$ref":"#/components/schemas/hq_Tier"},"status":{"$ref":"#/components/schemas/hq_LiveEnvironmentInfo"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","tier","status"]},"hq_Tier":{"type":"string","description":"Enumerates Tiers.","enum":["development","staging","production"]},"hq_LiveEnvironmentInfo":{"type":"object","description":"Contains dynamic properties of the Agent, brought in via a connected\nagent. Only when the agent is connected to HQ, agent info can be\nupdated. An environment that never had a connected agent cannot have a\nLiveAgentInfo.\n","properties":{"agent_connected":{"type":"boolean","description":"Signals whether an agent is currently connected."},"agent":{"$ref":"#/components/schemas/hq_LiveAgentInfo","description":"Initialised on first agent connect, and updated only while connected."}},"required":["agent_connected"]},"hq_LiveAgentInfo":{"type":"object","description":"Is a collection of fields related to an agent. Updated only when an agent is connected.\n","properties":{"updated_at":{"format":"date-time","type":"string","description":"Contains the time instant this object as a whole was updated."},"connected_at":{"format":"date-time","type":"string","description":"Contains the time instant the agent connected to HQ."},"roundtrip_duration":{"type":"number","format":"double","description":"Is measured in seconds."},"agent":{"$ref":"#/components/schemas/hq_LensesAgentSummary"},"metrics":{"$ref":"#/components/schemas/hq_AgentMetrics"}},"required":["updated_at","roundtrip_duration","agent"]},"hq_LensesAgentSummary":{"type":"object","description":"Bundles information about the agent.","properties":{"hostname":{"type":"string","description":"Is set to the hostname of the machine the agent runs on."},"version":{"type":"string","description":"Contains the version of the agent executable."},"protocol_version":{"type":"string","description":"Contains the internal protocol version implemented by the agent."},"capabilities":{"$ref":"#/components/schemas/hq_AgentCapabilities"}},"required":["hostname","version","capabilities","protocol_version"]},"hq_AgentCapabilities":{"type":"object","description":"Exposes capabilities of this particular agent.","properties":{"metrics":{"type":"boolean","description":"Is set to true if the agent can provide metrics."},"k2k":{"type":"boolean","description":"Is set to true if the agent can do Kafka2kafka."},"publish":{"type":"boolean","description":"Is set to true if the agent can publish to Kafka."}},"required":["metrics","k2k","publish"]},"hq_AgentMetrics":{"type":"object","description":"Bundles several categories of agent metrics.","properties":{"kafka":{"$ref":"#/components/schemas/hq_AgentKafkaMetrics"},"data":{"$ref":"#/components/schemas/hq_AgentDataMetrics"},"apps":{"$ref":"#/components/schemas/hq_AgentAppsMetrics"},"connect":{"$ref":"#/components/schemas/hq_AgentConnectMetrics"},"other":{"$ref":"#/components/schemas/hq_AgentOtherMetrics"}},"required":[]},"hq_AgentKafkaMetrics":{"type":"object","description":"Is optionally part of AgentMetrics. Contains Kafka-specific metrics.\nUnavailable if Zoopeeker is not configured.\n","properties":{"version":{"type":"string"},"num_brokers":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["version","num_brokers","updated_at"]},"hq_AgentDataMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Data related metrics.","properties":{"num_topics":{"type":"integer"},"num_partitions":{"type":"integer"},"num_schemas":{"type":"integer"},"num_policies":{"type":"integer"},"topic_data_total_bytes":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Total size of all topic data including\nreplicas on disk [bytes].\n"},"data_in_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [bytes/s].\n"},"data_out_bytes_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data read from the brokers [bytes/s].\n"},"data_in_messages_per_sec":{"type":"integer","format":"int64","description":"Is unavailable without Zookeeper. Data written to the brokers [msg/s].\n"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_topics","num_partitions","num_schemas","num_policies","updated_at"]},"hq_AgentAppsMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Apps metrics.","properties":{"num_consumers":{"type":"integer"},"num_other_apps":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_consumers","num_other_apps","updated_at"]},"hq_AgentConnectMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains Kafka Connect metrics.","properties":{"num_clusters":{"type":"integer"},"num_connectors":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_clusters","num_connectors","updated_at"]},"hq_AgentOtherMetrics":{"type":"object","description":"Is a part of AgentMetrics. Contains miscellaneous metrics.","properties":{"num_issues":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}},"required":["num_issues","updated_at"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{name}/renew-key":{"post":{"description":"Generates a new agent key and invalidates the old.","operationId":"renewEnvironmentKey","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_NewEnvironmentWithKey"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## GET /api/v1/environments/live/sse

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

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/live/sse":{"get":{"description":"Provides Server-Sent Events (SSE) for environment updates. TODO.","operationId":"observeEnvironmentUpdates","responses":{"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## GET /api/v2/environments/live/sse

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

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v2/environments/live/sse":{"get":{"description":"Server-Sent Events (SSE) stream of environment list changes. Wire format follows MDN SSE with\nnamed events: the JSON payload is carried in the data field and the event name is written in a\npreceding event field. Auth is applied per-item before emission. The server emits the following\nnamed events: initial (full current list, EnvironmentLiveItemsPayload), upsert (only changed or\ncreated environments, EnvironmentLiveItemsPayload), and delete (only deleted environment IDs,\nEnvironmentLiveDeletePayload).\n","operationId":"observeEnvironmentUpdatesV2","responses":{"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```

## GET /api/v1/environments/{name}/proxy/

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

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_environments","description":"Manage Lenses environments and configurations"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/environments/{name}/proxy/":{"get":{"description":"Proxies HTTP to a Lenses instance. Note: this is not a regular HTTP API\nendpoint. The path specified here is a prefix. Everything beneath it\ngets proxied to the corresponding Lenses instance. Any request body and\nmethod (the GET here is only a placeholder) are accepted, as long as the\nLenses API accepts it. The connection can even be upgraded to a\nwebsocket. The status code and response body are controlled by the\nLenses API. This concept does not fit into the OpenAPI world at all;\nthis definition is only here for the sake of documentation to avoid\nhaving an undocumented dark matter API.\n","operationId":"proxyToLensesAPI","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_environments"]}}}}
```