1 of 4

API Reference

This page describes the Lenses API references.

Lenses offers a set of REST and WebSocket APIs to help you provision and manage the application, make use of its capabilities, and query data via SQL.

Authentication API

This page describes how to authentication against Lenses APIs.

Basic Authentication

For Basic Auth, Lenses supports HTTP basic auth.

Service Accounts

The authenticate with service accounts, Lenses supports Bearer tokens. Set the token in the HTTP header request.

curl -L \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MY_SERVICE_ACCOUNT_TOKEN'
  'https://api.example.com/api/v1/login'

Lenses API Spec

API reference documentation for Lenses.

Authentication

Websocket Spec

Query Data via SQL

A WebSocket allows the client to request data using SQL as input.

Use the following URL to open a WebSocket connection. Depending on deployment, use ws (not-secure) or wss (secure) connection:

WS | WSS ${LENSES_URL}/environment/${YOU_ENVIRONMENT_NAME}/proxy/api/ws/v2/sql/execute

The query is per environment, you need to add the environment name.

Establishing a connection

To authenticate, create a service account and set the token in the header for the Authorization Bearer.

Once the connection is established, the server expects the client to send a JSON message with the following structure:

{
  "sql": String,
  "live": Optional[Boolean],
  "stats": Optional[Int]
}

For example in Python:

import os, websockets, json, async

async def execute_SQL (environmentName: Annotated[str, "The environment to execute to sql against"], 
                       sql: Annotated[str, "SQL Statement to run"]=None ) -> Annotated[dict, "The response from the API for SQL"]:
    """
    Calls a REST API and returns the response.

    :param sql: SQL Statement to run
    :return: The response from the API.
    """
    
    url = os.getenv("HQ_URL").replace("https", "wss").strip("/") + "/api/v1/environments/" + environmentName + "/proxy/api/ws/v2/sql/execute"
    headers = {"Authorization": "Bearer " + os.getenv('HQ_PASSWORD')}	
         
    data = []
    try:       
        request = {           
            "sql": sql,
            "live": False,
            "stats": 2
        }
        
        async with websockets.connect(url, additional_headers=headers) as websocket:
            await websocket.send(json.dumps(request))
            async for message in websocket:
                response = json.loads(message)
                if response.get('type') == 'RECORD':
                    data.append(response)
        
    except requests.exceptions.RequestException as e:
        print(f"An error occurred: {e}")
        return None  
    print(data)
    
asyncio.run(execute_SQL("us-prod", "SELECT * FROM airline-orders WHERE _meta.offset >= LAST_OFFSET() - 10 LIMIT 100;"))

Query Request

Field

Description

Type

sql

The SQL query used to fetch data

string

live

If set, enables partial results for aggregation queries.

optional[boolean]

stats

Millis interval to receive query stats. If not provided the stats information is not sent

optional[int]

Protocol

The client should wait for incoming messages and stop when EOF is received. The server sends JSON-encoded messages, the payload structure is:

{
  "type": <Enumeration>,
  "data": <Dependent on the type field>
}

Since there are multiple types of messages the server sends, the type attribute determines the data structure for the data payload. Below is the list of possible type values:

Value

Description

HEARTBEAT

To keep the connection alive, the server injects an empty message.

RECORD

The message represents a data record.

ERROR

The message contains information about an error that occurred.

STATS

The message contains information about the current execution.Only activated if the stats field in the request is present.

METADATA

The message contains a list of metadata fields each record message will contain. For example: offset, partition,timestamp, __keysize, __valueSize, valueSchemaId.

SCHEMA

Reserved.

PAGE_END

Reserved.

END

The message signals the end of the execution. The server will close the socket after this message is sent.

BADRECORD

The message contains information about the Kafka message which cannot be read. For example, if the topic expects Avro and the payload is not a valid Avro.

SENTINEL

The message contains information about the execution termination reason when query thresholds are reached.

Heartbeat

The data the attribute is null. The client should ignore these messages.

{
  "type": "HEARTBEAT"
}

Error

In this case, the payload structure is:

{
  "type": "HEARTBEAT",
  "data": String
}

Stats

When requested the payload format is:

{
  "type": "HEARTBEAT",
  "data":   {
    id:              String,
    bytesRead:       Long,
    sources:         Map[UUID, String],
    sourceConfigs:   Map[UUID, Map[String, Any]],
    sourcesStats:    Map[UUID, Map[Int, Map[String, Long]]],
    badRecordsTotal: Long,
    recordsSkipped:  Long,
    results:         Long,
    recordsScanned:  Long,
    duration:        Long,
    startedAt:       Long,
}

A possible payload can be:

{
  "type": "STATS",
  "data": {
    "id": "6a29ef99-3914-4640-b0dc-ec4a07c7ffc5",
    "bytesRead": 51972426,
    "sources": {
      "ad1afc73-3dec-41e7-b679-aa35c55e3328": "cc_payments"
    },
    "sourceConfigs": {
      "ad1afc73-3dec-41e7-b679-aa35c55e3328": {
        "live.aggs": true,
        "max.idle.time": 20000,
        "format.timestamp": true,
        "show.bad.records": true,
        "kafka.offset.timeout": 10000,
        "max.query.time": 3600000,
        "max.size": 209715200
      }
    },
    "sourcesStats": {
      "ad1afc73-3dec-41e7-b679-aa35c55e3328": {
        "0": {
          "begin": 0,
          "offsetBound": 541950,
          "bytesRead": 51972426,
          "recordsScanned": 541951,
          "end": 541950
        }
      }
    },
    "badRecordsTotal": 0,
    "recordsSkipped": 0,
    "results": 119,
    "recordsScanned": 541951,
    "duration": 18196,
    "startedAt": 1678901355694
  }
}

Metadata

The payload format is:

{
  "type": "METADATA",
  "data": {
    "fields": Array[String]
  }
}

End

The payload format is:

{
  "type": "END"
}

Bad Record

The payload format is:

{
  "type": "BADRECORD",
  "data": {
    "metadata": {
      "offset": Optional[Long],
      "partition": Optional[Long],
      "timestamp": Optional[Long],
      "table": String,
      "sourceId": String
    }
  }
}

Sentinel

The payload format is:

{
  "type": "SENTINEL",
  "data": {
    "event": String,
    "reason": {
      "type": String,
      "timeout":  Optional[Long],
      "source":   String,
      "sourceId": String,
      "amount":Long        
    }
  }
}

Record

Given the type RECORD the payloads contains the data returned to the client, and it is dependent on the SQL input. The payload format is:

{
  "type": "RECORD",
  "data": {
    "fields": <dynamic>,
    "value": <dynamic>,
    "metadata": <dynamic>,
    "rownum": Optional[Long]
  }
}

Value

Description

data.key

Returns the underlying Kafka message key value. Only applied when * projection is used. When a key projection is used (i.e. _key.MMSI), the value is returned as data.value.MMSI.

data.data

Will contain the output generated by the SQL projections. If * is used for the SQL projection, it will return the Kafka message value structure.

data.metadata

Returned when no aggregations are involved. It contains the Kafka message partition, offset, byte size information

data.rownum

Reserved optional long value.

Examples

For a topic which contains nested data for both key and value.

SELECT * FROM sea_vessel_position_reports

The payload format is:

{
  "type": "RECORD",
  "data": {
    "key": {
      "MMSI": 219005662
    },
    "value": {
      "Type": 1,
      "Repeat": 0,
      "MMSI": 219005662,
      "Speed": 0.1,
      "Accuracy": false,
      "Longitude": 12.570543333333333,
      "Latitude": 55.85040166666667,
      "location": "55.850402,12.570543",
      "Course": 177.9,
      "Heading": 511,
      "Second": 20,
      "RAIM": false,
      "Radio": 33577,
      "Status": 3,
      "Turn": -128.0,
      "Maneuver": 0,
      "Timestamp": 1491318144456507320
    },
    "metadata": {
      "offset": 71,
      "partition": 1,
      "timestamp": "2023-03-13T11:42:24.267Z",
      "__keysize": 10,
      "__valuesize": 79,
      "keySchemaId": 4,
      "valueSchemaId": 5
    },
    "rownum": 71
  }
}

If the Kafka message key is null the response would be:

{
  "type": "RECORD",
  "data": {
    "value": {
      "Type": 1,
      "Repeat": 0,
      "MMSI": 219005662,
      "Speed": 0.1,
      "Accuracy": false,
      "Longitude": 12.570543333333333,
      "Latitude": 55.85040166666667,
      "location": "55.850402,12.570543",
      "Course": 177.9,
      "Heading": 511,
      "Second": 20,
      "RAIM": false,
      "Radio": 33577,
      "Status": 3,
      "Turn": -128.0,
      "Maneuver": 0,
      "Timestamp": 1491318144456507320
    },
    "metadata": {
      "offset": 71,
      "partition": 1,
      "timestamp": "2023-03-13T11:42:24.267Z",
      "__keysize": 10,
      "__valuesize": 79,
      "keySchemaId": 4,
      "valueSchemaId": 5
    },
    "rownum": 71
  }
}

Projecting the key will not return the key attribute:

SELECT _key.MMSI FROM sea_vessel_position_reports

produces the following output:

{
  "type": "RECORD",
  "data": {
    "value": {
      "MMSI": 265527470
    },
    "metadata": {
      "offset": 86,
      "partition": 1,
      "timestamp": "2023-03-13T11:42:29.107Z",
      "__keysize": 10,
      "__valuesize": 79,
      "keySchemaId": 4,
      "valueSchemaId": 5
    },
    "rownum": 86
  }
}

Aggregating data will not return the key and metadata attributes:

SELECT count(*), currency 
FROM cc_payments
GROUP BY currency

{
  "type": "RECORD",
  "data": {
    "value": {
      "count": 20066,
      "currency": "NOR"
    },
    "rownum": 90
  },
  "rowId": "fc767952-97e5-46cf-868c-7cbfbcde21fb",
  "statementIndex": null
}

Websocket Spec

Query Data via SQL

A WebSocket allows the client to request data using SQL as input.

Use the following URL to open a WebSocket connection. Depending on deployment, use ws (not-secure) or wss (secure) connection:

WS | WSS ${LENSES_URL}/environment/${YOU_ENVIRONMENT_NAME}/proxy/api/ws/v2/sql/execute

The query is per environment, you need to add the environment name.

Establishing a connection

To authenticate, create a service account and set the token in the header for the Authorization Bearer.

Once the connection is established, the server expects the client to send a JSON message with the following structure:

{
  "sql": String,
  "live": Optional[Boolean],
  "stats": Optional[Int]
}

For example in Python:

import os, websockets, json, async

async def execute_SQL (environmentName: Annotated[str, "The environment to execute to sql against"], 
                       sql: Annotated[str, "SQL Statement to run"]=None ) -> Annotated[dict, "The response from the API for SQL"]:
    """
    Calls a REST API and returns the response.

    :param sql: SQL Statement to run
    :return: The response from the API.
    """
    
    url = os.getenv("HQ_URL").replace("https", "wss").strip("/") + "/api/v1/environments/" + environmentName + "/proxy/api/ws/v2/sql/execute"
    headers = {"Authorization": "Bearer " + os.getenv('HQ_PASSWORD')}	
         
    data = []
    try:       
        request = {           
            "sql": sql,
            "live": False,
            "stats": 2
        }
        
        async with websockets.connect(url, additional_headers=headers) as websocket:
            await websocket.send(json.dumps(request))
            async for message in websocket:
                response = json.loads(message)
                if response.get('type') == 'RECORD':
                    data.append(response)
        
    except requests.exceptions.RequestException as e:
        print(f"An error occurred: {e}")
        return None  
    print(data)
    
asyncio.run(execute_SQL("us-prod", "SELECT * FROM airline-orders WHERE _meta.offset >= LAST_OFFSET() - 10 LIMIT 100;"))

Query Request

Field

Description

Type

sql

The SQL query used to fetch data

string

live

If set, enables partial results for aggregation queries.

optional[boolean]

stats

Millis interval to receive query stats. If not provided the stats information is not sent

optional[int]

Protocol

The client should wait for incoming messages and stop when EOF is received. The server sends JSON-encoded messages, the payload structure is:

{
  "type": <Enumeration>,
  "data": <Dependent on the type field>
}

Since there are multiple types of messages the server sends, the type attribute determines the data structure for the data payload. Below is the list of possible type values:

Value

Description

HEARTBEAT

To keep the connection alive, the server injects an empty message.

RECORD

The message represents a data record.

ERROR

The message contains information about an error that occurred.

STATS

The message contains information about the current execution.Only activated if the stats field in the request is present.

METADATA

The message contains a list of metadata fields each record message will contain. For example: offset, partition,timestamp, __keysize, __valueSize, valueSchemaId.

SCHEMA

Reserved.

PAGE_END

Reserved.

END

The message signals the end of the execution. The server will close the socket after this message is sent.

BADRECORD

The message contains information about the Kafka message which cannot be read. For example, if the topic expects Avro and the payload is not a valid Avro.

SENTINEL

The message contains information about the execution termination reason when query thresholds are reached.

Heartbeat

The data the attribute is null. The client should ignore these messages.

{
  "type": "HEARTBEAT"
}

Error

In this case, the payload structure is:

{
  "type": "HEARTBEAT",
  "data": String
}

Stats

When requested the payload format is:

{
  "type": "HEARTBEAT",
  "data":   {
    id:              String,
    bytesRead:       Long,
    sources:         Map[UUID, String],
    sourceConfigs:   Map[UUID, Map[String, Any]],
    sourcesStats:    Map[UUID, Map[Int, Map[String, Long]]],
    badRecordsTotal: Long,
    recordsSkipped:  Long,
    results:         Long,
    recordsScanned:  Long,
    duration:        Long,
    startedAt:       Long,
}

A possible payload can be:

{
  "type": "STATS",
  "data": {
    "id": "6a29ef99-3914-4640-b0dc-ec4a07c7ffc5",
    "bytesRead": 51972426,
    "sources": {
      "ad1afc73-3dec-41e7-b679-aa35c55e3328": "cc_payments"
    },
    "sourceConfigs": {
      "ad1afc73-3dec-41e7-b679-aa35c55e3328": {
        "live.aggs": true,
        "max.idle.time": 20000,
        "format.timestamp": true,
        "show.bad.records": true,
        "kafka.offset.timeout": 10000,
        "max.query.time": 3600000,
        "max.size": 209715200
      }
    },
    "sourcesStats": {
      "ad1afc73-3dec-41e7-b679-aa35c55e3328": {
        "0": {
          "begin": 0,
          "offsetBound": 541950,
          "bytesRead": 51972426,
          "recordsScanned": 541951,
          "end": 541950
        }
      }
    },
    "badRecordsTotal": 0,
    "recordsSkipped": 0,
    "results": 119,
    "recordsScanned": 541951,
    "duration": 18196,
    "startedAt": 1678901355694
  }
}

Metadata

The payload format is:

{
  "type": "METADATA",
  "data": {
    "fields": Array[String]
  }
}

End

The payload format is:

{
  "type": "END"
}

Bad Record

The payload format is:

{
  "type": "BADRECORD",
  "data": {
    "metadata": {
      "offset": Optional[Long],
      "partition": Optional[Long],
      "timestamp": Optional[Long],
      "table": String,
      "sourceId": String
    }
  }
}

Sentinel

The payload format is:

{
  "type": "SENTINEL",
  "data": {
    "event": String,
    "reason": {
      "type": String,
      "timeout":  Optional[Long],
      "source":   String,
      "sourceId": String,
      "amount":Long        
    }
  }
}

Record

Given the type RECORD the payloads contains the data returned to the client, and it is dependent on the SQL input. The payload format is:

{
  "type": "RECORD",
  "data": {
    "fields": <dynamic>,
    "value": <dynamic>,
    "metadata": <dynamic>,
    "rownum": Optional[Long]
  }
}

Value

Description

data.key

Returns the underlying Kafka message key value. Only applied when * projection is used. When a key projection is used (i.e. _key.MMSI), the value is returned as data.value.MMSI.

data.data

Will contain the output generated by the SQL projections. If * is used for the SQL projection, it will return the Kafka message value structure.

data.metadata

Returned when no aggregations are involved. It contains the Kafka message partition, offset, byte size information

data.rownum

Reserved optional long value.

Examples

For a topic which contains nested data for both key and value.

SELECT * FROM sea_vessel_position_reports

The payload format is:

{
  "type": "RECORD",
  "data": {
    "key": {
      "MMSI": 219005662
    },
    "value": {
      "Type": 1,
      "Repeat": 0,
      "MMSI": 219005662,
      "Speed": 0.1,
      "Accuracy": false,
      "Longitude": 12.570543333333333,
      "Latitude": 55.85040166666667,
      "location": "55.850402,12.570543",
      "Course": 177.9,
      "Heading": 511,
      "Second": 20,
      "RAIM": false,
      "Radio": 33577,
      "Status": 3,
      "Turn": -128.0,
      "Maneuver": 0,
      "Timestamp": 1491318144456507320
    },
    "metadata": {
      "offset": 71,
      "partition": 1,
      "timestamp": "2023-03-13T11:42:24.267Z",
      "__keysize": 10,
      "__valuesize": 79,
      "keySchemaId": 4,
      "valueSchemaId": 5
    },
    "rownum": 71
  }
}

If the Kafka message key is null the response would be:

{
  "type": "RECORD",
  "data": {
    "value": {
      "Type": 1,
      "Repeat": 0,
      "MMSI": 219005662,
      "Speed": 0.1,
      "Accuracy": false,
      "Longitude": 12.570543333333333,
      "Latitude": 55.85040166666667,
      "location": "55.850402,12.570543",
      "Course": 177.9,
      "Heading": 511,
      "Second": 20,
      "RAIM": false,
      "Radio": 33577,
      "Status": 3,
      "Turn": -128.0,
      "Maneuver": 0,
      "Timestamp": 1491318144456507320
    },
    "metadata": {
      "offset": 71,
      "partition": 1,
      "timestamp": "2023-03-13T11:42:24.267Z",
      "__keysize": 10,
      "__valuesize": 79,
      "keySchemaId": 4,
      "valueSchemaId": 5
    },
    "rownum": 71
  }
}

Projecting the key will not return the key attribute:

SELECT _key.MMSI FROM sea_vessel_position_reports

produces the following output:

{
  "type": "RECORD",
  "data": {
    "value": {
      "MMSI": 265527470
    },
    "metadata": {
      "offset": 86,
      "partition": 1,
      "timestamp": "2023-03-13T11:42:29.107Z",
      "__keysize": 10,
      "__valuesize": 79,
      "keySchemaId": 4,
      "valueSchemaId": 5
    },
    "rownum": 86
  }
}

Aggregating data will not return the key and metadata attributes:

SELECT count(*), currency 
FROM cc_payments
GROUP BY currency

{
  "type": "RECORD",
  "data": {
    "value": {
      "count": 20066,
      "currency": "NOR"
    },
    "rownum": 90
  },
  "rowId": "fc767952-97e5-46cf-868c-7cbfbcde21fb",
  "statementIndex": null
}

Lenses API Spec

API reference documentation for Lenses.

Authentication

Starts a session given a username/password and puts it into a cookie.

POSThttps://api.example.com/api/v1/login

Body

username*string

password*string

Response

Happy response. A set-cookie header will be present.

Request

Lists all environments

GEThttps://api.example.com/api/v1/environments

Response

Happy response.

Body

items*array of Environment (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

status*LiveEnvironmentInfo (object)

Contains dynamic properties of the Agent, brought in via a connected agent. Only when the agent is connected to HQ, agent info can be updated. An environment that never had a connected agent cannot have a LiveAgentInfo.

agent_connected*boolean

Signals whether an agent is currently connected.

agentLiveAgentInfo (object)

Is a collection of fields related to an agent. Updated only when an agent is connected.

updated_at*string (date-time)

Contains the time instant this object as a whole was updated.

roundtrip_duration*number (double)

Is measured in seconds.

agent*LensesAgentSummary (object)

Bundles licence info as gathered by the agent through Lenses' API.

hostname*string

Is set to the hostname of the machine the agent runs on.

version*string

Contains the version of the agent executable.

metricsAgentMetrics (object)

Bundles several categories of agent metrics.

kafkaAgentKafkaMetrics (object)

Is optionally part of AgentMetrics. Contains Kafka-specific metrics. Unavailable if Zoopeeker is not configured.

version*string

num_brokers*integer

updated_at*string (date-time)

data*AgentDataMetrics (object)

Is a part of AgentMetrics. Contains Data related metrics.

num_topics*integer

num_partitions*integer

num_schemas*integer

num_policies*integer

topic_data_total_bytesinteger (int64)

Is unavailable without Zookeeper. Total size of all topic data including replicas on disk [bytes].

data_in_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [bytes/s].

data_out_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data read from the brokers [bytes/s].

data_in_messages_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [msg/s].

updated_at*string (date-time)

apps*AgentAppsMetrics (object)

Is a part of AgentMetrics. Contains Apps metrics.

num_consumers*integer

num_other_apps*integer

updated_at*string (date-time)

connect*AgentConnectMetrics (object)

Is a part of AgentMetrics. Contains Kafka Connect metrics.

num_clusters*integer

num_connectors*integer

updated_at*string (date-time)

other*AgentOtherMetrics (object)

Is a part of AgentMetrics. Contains miscellaneous metrics.

num_issues*integer

updated_at*string (date-time)

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Creates a new environment.

POSThttps://api.example.com/api/v1/environments

Body

name*string (hq-resource-name)

Sets the name of the new environment. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring

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

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Response

Happy response.

Body

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

status*LiveEnvironmentInfo (object)

agent_connected*boolean

Signals whether an agent is currently connected.

agentLiveAgentInfo (object)

Is a collection of fields related to an agent. Updated only when an agent is connected.

updated_at*string (date-time)

Contains the time instant this object as a whole was updated.

roundtrip_duration*number (double)

Is measured in seconds.

agent*LensesAgentSummary (object)

Bundles licence info as gathered by the agent through Lenses' API.

hostname*string

Is set to the hostname of the machine the agent runs on.

version*string

Contains the version of the agent executable.

metricsAgentMetrics (object)

Bundles several categories of agent metrics.

kafkaAgentKafkaMetrics (object)

Is optionally part of AgentMetrics. Contains Kafka-specific metrics. Unavailable if Zoopeeker is not configured.

version*string

num_brokers*integer

updated_at*string (date-time)

data*AgentDataMetrics (object)

Is a part of AgentMetrics. Contains Data related metrics.

num_topics*integer

num_partitions*integer

num_schemas*integer

num_policies*integer

topic_data_total_bytesinteger (int64)

Is unavailable without Zookeeper. Total size of all topic data including replicas on disk [bytes].

data_in_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [bytes/s].

data_out_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data read from the brokers [bytes/s].

data_in_messages_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [msg/s].

updated_at*string (date-time)

apps*AgentAppsMetrics (object)

Is a part of AgentMetrics. Contains Apps metrics.

num_consumers*integer

num_other_apps*integer

updated_at*string (date-time)

connect*AgentConnectMetrics (object)

Is a part of AgentMetrics. Contains Kafka Connect metrics.

num_clusters*integer

num_connectors*integer

updated_at*string (date-time)

other*AgentOtherMetrics (object)

Is a part of AgentMetrics. Contains miscellaneous metrics.

num_issues*integer

updated_at*string (date-time)

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

agent_key*string

Request

Response

Retrieves a single environment by name.

GEThttps://api.example.com/api/v1/environments/{name}

Path parameters

name*string

Response

Happy response.

Body

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

status*LiveEnvironmentInfo (object)

agent_connected*boolean

Signals whether an agent is currently connected.

agentLiveAgentInfo (object)

Is a collection of fields related to an agent. Updated only when an agent is connected.

updated_at*string (date-time)

Contains the time instant this object as a whole was updated.

roundtrip_duration*number (double)

Is measured in seconds.

agent*LensesAgentSummary (object)

Bundles licence info as gathered by the agent through Lenses' API.

hostname*string

Is set to the hostname of the machine the agent runs on.

version*string

Contains the version of the agent executable.

metricsAgentMetrics (object)

Bundles several categories of agent metrics.

kafkaAgentKafkaMetrics (object)

Is optionally part of AgentMetrics. Contains Kafka-specific metrics. Unavailable if Zoopeeker is not configured.

version*string

num_brokers*integer

updated_at*string (date-time)

data*AgentDataMetrics (object)

Is a part of AgentMetrics. Contains Data related metrics.

num_topics*integer

num_partitions*integer

num_schemas*integer

num_policies*integer

topic_data_total_bytesinteger (int64)

Is unavailable without Zookeeper. Total size of all topic data including replicas on disk [bytes].

data_in_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [bytes/s].

data_out_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data read from the brokers [bytes/s].

data_in_messages_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [msg/s].

updated_at*string (date-time)

apps*AgentAppsMetrics (object)

Is a part of AgentMetrics. Contains Apps metrics.

num_consumers*integer

num_other_apps*integer

updated_at*string (date-time)

connect*AgentConnectMetrics (object)

Is a part of AgentMetrics. Contains Kafka Connect metrics.

num_clusters*integer

num_connectors*integer

updated_at*string (date-time)

other*AgentOtherMetrics (object)

Is a part of AgentMetrics. Contains miscellaneous metrics.

num_issues*integer

updated_at*string (date-time)

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Updates an environment.

PATCHhttps://api.example.com/api/v1/environments/{name}

Path parameters

name*string

Body

tierTier (enum)

Enumerates Tiers.

developmentstagingproduction

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Other propertiesnullable string

display_namestring

Updates the display name of the environment.

Response

Happy response.

Body

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

status*LiveEnvironmentInfo (object)

agent_connected*boolean

Signals whether an agent is currently connected.

agentLiveAgentInfo (object)

Is a collection of fields related to an agent. Updated only when an agent is connected.

updated_at*string (date-time)

Contains the time instant this object as a whole was updated.

roundtrip_duration*number (double)

Is measured in seconds.

agent*LensesAgentSummary (object)

Bundles licence info as gathered by the agent through Lenses' API.

hostname*string

Is set to the hostname of the machine the agent runs on.

version*string

Contains the version of the agent executable.

metricsAgentMetrics (object)

Bundles several categories of agent metrics.

kafkaAgentKafkaMetrics (object)

Is optionally part of AgentMetrics. Contains Kafka-specific metrics. Unavailable if Zoopeeker is not configured.

version*string

num_brokers*integer

updated_at*string (date-time)

data*AgentDataMetrics (object)

Is a part of AgentMetrics. Contains Data related metrics.

num_topics*integer

num_partitions*integer

num_schemas*integer

num_policies*integer

topic_data_total_bytesinteger (int64)

Is unavailable without Zookeeper. Total size of all topic data including replicas on disk [bytes].

data_in_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [bytes/s].

data_out_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data read from the brokers [bytes/s].

data_in_messages_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [msg/s].

updated_at*string (date-time)

apps*AgentAppsMetrics (object)

Is a part of AgentMetrics. Contains Apps metrics.

num_consumers*integer

num_other_apps*integer

updated_at*string (date-time)

connect*AgentConnectMetrics (object)

Is a part of AgentMetrics. Contains Kafka Connect metrics.

num_clusters*integer

num_connectors*integer

updated_at*string (date-time)

other*AgentOtherMetrics (object)

Is a part of AgentMetrics. Contains miscellaneous metrics.

num_issues*integer

updated_at*string (date-time)

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Deletes an environment.

DELETEhttps://api.example.com/api/v1/environments/{name}

Path parameters

name*string

Response

Successful deletion.

Request

Response

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.

GEThttps://api.example.com/api/v1/environments/{name}/proxy/

Path parameters

name*string

Response

Error object.

Body

typeErrorType (enum)

Enumerates possible error types.

not_foundunauthorisedforbiddeninternal_server_erroragent_not_connectedvalidation_errorinvalid_metadatamissing_parameterinvalid_parameterlicence_limitation_violatedunspecified

title*string

Describes the problem in a human readable fashion.

status*integer

Is a copy of the http status code.

invalid_fieldsarray of InvalidField (object)

Lists for validation errors the fields that failed validation.

name*string

error*FieldErrorType (enum)

Enumerates field validation error types.

reference_not_foundnot_uniqueinvalid_valueother_error

title*string

sso_urlstring

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

request_idstring

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

Request

Response

Get a single dataset by connection/name. While information mastered externally might be a few second out of sync with their respective sources (e.g. JMX metadata, Elasticsearch index status, etc), information mastered in Lenses's db is guaranteed to be up to date (e.g. tags, descriptions).

GEThttps://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/{connection}/{dataset}

Path parameters

name*string

connection*string

Example: "kafka"

dataset*string

Example: "customer-positions"

Response

Body

DatasetMatch (one of)

name*string

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

recordsinteger (int64)

recordsPerSecond*integer (int64)

keyType*string

valueType*string

connectionName*string

replication*integer

consumers*integer

partitions*integer

fieldsFields (object)

keyarray of Field (object)

name*string

typestring

typeDetails*FieldTypeDetails (one of)

lensesDataType*string

descriptionstring

ancestorsarray of string

itemsstring

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

isNullable*boolean

defaultstring

valuearray of Field (object)

name*string

typestring

typeDetails*FieldTypeDetails (one of)

lensesDataType*string

descriptionstring

ancestorsarray of string

itemsstring

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

isNullable*boolean

defaultstring

isSystemEntity*boolean

isMarkedForDeletion*boolean

isCompacted*boolean

sizeBytesinteger (int64)

policiesarray of PolicyMatchDetails (object)

policyId*string

policyName*string

policyCategory*string

obfuscation*string

matchingKeyFieldsarray of PolicyFieldMatch (object)

name*string

parentsarray of string

itemsstring

matchingValueFieldsarray of PolicyFieldMatch (object)

name*string

parentsarray of string

itemsstring

permissions*array of string

itemsstring

descriptionstring

tagsarray of DatasetTag (object)

name*string

count*number

retentionMsinteger (int64)

retentionBytesinteger (int64)

backupRestoreStateBackupRestoreState (one of)

sourceType*string

Request

Response

Retrieves a list of datasets

GEThttps://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets

Path parameters

name*string

Query parameters

pageinteger

The page number to be returned, must be greater than zero. Defaults to 1.

Example: 1

pageSize*integer

The elements amount on a single page, must be greater than zero.

Example: 25

querystring

A search keyword to match dataset, fields and description against.

Example: "name"

connectionsarray of string

A list of connection names to filter by. All connections will be included when no value is supplied.

itemsstring

tagsarray of string

A list of tag names to filter by. All tags will be included when no value is supplied.

itemsstring

sortByDatasetField (enum)

The field to sort results by

namerecordsconnectionNamesourceTypeisSystemEntityrecordsPerSecondkeyTypevalueTypereplicationconsumerspartitionsretentionBytesretentionMssizeBytesreplicasshardversionformatcompatibilitybackupRestoreState

sortingOrderOrder (enum)

Sorting order. Defaults to ascending

ascdesc

includeSystemEntitiesboolean

A flag to include in the search also system entities (e.g. Kafka's __consumer_offsets topic).

includeMetadataboolean

Whether to search only by table name, or also to include field names/documentation (defaults to true)

formatarray of string

Schema format. Relevant only when sourceType is SchemaRegistrySubject

itemsstring

hasRecordsboolean

Filter based on whether the dataset has records

compactedboolean

Filter based on compacted. Relevant only when sourceType is Kafka

Response

A response wrapping a paginated list of datasets and the set of relative source types

Body

datasets*Page_DatasetMatch (object)

valuesarray of Kafka (object)

name*string

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

recordsinteger (int64)

recordsPerSecond*integer (int64)

keyType*string

valueType*string

connectionName*string

replication*integer

consumers*integer

partitions*integer

fieldsFields (object)

keyarray of Field (object)

name*string

typestring

typeDetails*FieldTypeDetails (one of)

lensesDataType*string

descriptionstring

ancestorsarray of string

itemsstring

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

isNullable*boolean

defaultstring

valuearray of Field (object)

name*string

typestring

typeDetails*FieldTypeDetails (one of)

lensesDataType*string

descriptionstring

ancestorsarray of string

itemsstring

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

isNullable*boolean

defaultstring

isSystemEntity*boolean

isMarkedForDeletion*boolean

isCompacted*boolean

sizeBytesinteger (int64)

policiesarray of PolicyMatchDetails (object)

policyId*string

policyName*string

policyCategory*string

obfuscation*string

matchingKeyFieldsarray of PolicyFieldMatch (object)

name*string

parentsarray of string

itemsstring

matchingValueFieldsarray of PolicyFieldMatch (object)

name*string

parentsarray of string

itemsstring

permissions*array of string

itemsstring

descriptionstring

tagsarray of DatasetTag (object)

name*string

count*number

retentionMsinteger (int64)

retentionBytesinteger (int64)

backupRestoreStateBackupRestoreState (one of)

sourceType*string

pagesAmount*integer (int64)

totalCount*integer (int64)

sourceTypesarray of SourceType (enum)

itemsSourceType (enum)

KafkaElasticPostgresSchemaRegistrySubject

Request

Response

Retrieves a list of dataset tags

GEThttps://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/tags

Path parameters

name*string

Query parameters

querystring

Get tags sorted by dataset count

Example: "user"

Response

A response wrapping a paginated list of datasets and the set of relative source types

Body

tags*array of DatasetTag (object)

name*string

count*number

Request

Response

Lists all groups

GEThttps://api.example.com/api/v1/groups

Response

Happy response.

Body

items*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Creates a new Group.

POSThttps://api.example.com/api/v1/groups

Body

name*string (hq-resource-name)

Sets the unique name of the new group. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring

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

descriptionstring

Sets the description of the new group.

membersarray of string

Lists principal names (users, service accounts) to be member of this group.

itemsstring

rolesarray of string

Sets the Roles that are bound to this Group by name.

itemsstring

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Response

Happy response.

Body

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy_length*integer

Is set to the number of PermissionStatements in the Policy.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

users*array of CompactUser (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

service_accounts*array of CompactServiceAccount (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Gets a group by its name.

GEThttps://api.example.com/api/v1/groups/{name}

Path parameters

name*string

Response

Happy response.

Body

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy_length*integer

Is set to the number of PermissionStatements in the Policy.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

users*array of CompactUser (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

service_accounts*array of CompactServiceAccount (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Returns all users

GEThttps://api.example.com/api/v1/users

Response

Happy response.

Body

items*array of User (object)

name*string

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Deletes a group.

DELETEhttps://api.example.com/api/v1/groups/{name}

Path parameters

name*string

Response

Successful deletion.

Request

Response

Updates a group.

PATCHhttps://api.example.com/api/v1/groups/{name}

Path parameters

name*string

Body

display_namestring

Updates the display name of the group.

descriptionstring

Updates the Group description, if a value is provided.

rolesarray of string

Sets the Roles that are bound to this Group to the Roles (specified by their names), if provided.

itemsstring

add_membersarray of string

Adds the users/principals (specified by their names) to this group, if provided.

itemsstring

remove_membersarray of string

Removes the users/principals (specified by their names) from this group, if provided. If members are specified in both add_members as well in here, removal wins.

itemsstring

set_membersarray of string

Sets the members of this group to those users/principals (specified by their names) in an absolute fashion, if provided. Cannot be combined with the add_members or remove_members fields.

itemsstring

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Other propertiesnullable string

Response

Happy response.

Body

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy_length*integer

Is set to the number of PermissionStatements in the Policy.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

users*array of CompactUser (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

service_accounts*array of CompactServiceAccount (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Creates a new user.

POSThttps://api.example.com/api/v1/users

Body

name*string

Sets the unique name of the new user. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring

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

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Response

Happy response.

Body

name*string

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Returns a specific user

GEThttps://api.example.com/api/v1/users/{name}

Path parameters

name*string

Response

Happy response.

Body

name*string

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Updates a user.

PATCHhttps://api.example.com/api/v1/users/{name}

Path parameters

name*string

Body

display_namestring

Updates the display name of the user.

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Other propertiesnullable string

Response

Happy response.

Body

name*string

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Deletes a user.

DELETEhttps://api.example.com/api/v1/users/{name}

Path parameters

name*string

Response

Successful deletion.

Request

Response

Allows updating fields of the user profile.

PATCHhttps://api.example.com/api/v1/users/{name}/profile

Path parameters

name*string

Body

full_namestring

Contains the users' full name, e.g. Mary Jane Doe.

email_addressstring

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

Response

Happy response.

Body

name*string

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Returns the currently authenticated user

GEThttps://api.example.com/api/v1/users/me

Response

Happy response.

Body

UserOrServiceAccount (object)

Represents either a user or service account.

name*string

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Assigns the given user exactly to the provided groups, ensuring they are not part of any other groups.

PUThttps://api.example.com/api/v1/users/{name}/groups

Path parameters

name*string

The name of the user.

Body

add_to_groupsarray of string

Adds the user or service account to the groups (specified by their names).

itemsstring

remove_from_groupsarray of string

Removes the user or service account from the groups (specified by their names). If a group is specified in both add_to_groups as well in here, removal wins.

itemsstring

set_groupsarray of string

Sets the user or service account memberships to those groups (specified by their names) in an absolute fashion (ensures user/sa will be exactly a member of those), if provided. Cannot be combined with the add_to_groups or remove_from_groups.

itemsstring

Response

User groups membership updated successfully.

Body

name*string

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Starts a session given a username/password and puts it into a cookie.

POSThttps://api.example.com/api/v1/login

Body

username*string

password*string

Response

Happy response. A set-cookie header will be present.

Request

Deletes all sessions associated with the current user.

DELETEhttps://api.example.com/api/v1/users/me/sessions

Response

Happy response.

Request

Response

Returns all ServiceAccounts.

GEThttps://api.example.com/api/v1/service-accounts

Response

Happy response.

Body

items*array of ServiceAccount (object)

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Creates a new ServiceAccount.

POSThttps://api.example.com/api/v1/service-accounts

Body

name*string (hq-resource-name)

Sets the unique name of the new service account. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring

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

descriptionstring

Sets the description of the new service account.

token_expires_atstring (date-time)

Determines the moment of token expiration. If not specified, the token will never expire.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Response

Happy response.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

token*string

Request

Response

Returns a specific ServiceAccount.

GEThttps://api.example.com/api/v1/service-accounts/{name}

Path parameters

name*string

Response

Happy response.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Updates a service account.

PATCHhttps://api.example.com/api/v1/service-accounts/{name}

Path parameters

name*string

Body

display_namestring

Updates the display name of the service account.

descriptionstring

Updates the description of a service account.

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Other propertiesnullable string

Response

Happy response.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Deletes a ServiceAccount.

DELETEhttps://api.example.com/api/v1/service-accounts/{name}

Path parameters

name*string

Response

Successful deletion.

Request

Response

Renews the service account's token. The current token is invalidated and a new one is generated. An optional expiration timestamp can be provided.

POSThttps://api.example.com/api/v1/service-accounts/{name}/renew-token

Path parameters

name*string

Body

token_expires_atstring (date-time)

Determines the moment of token expiration. If not specified, the token will never expire.

Response

Happy response.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

token*string

Request

Response

Assigns the given service account exactly to the provided groups, ensuring they are not part of any other groups.

PUThttps://api.example.com/api/v1/service-accounts/{name}/groups

Path parameters

name*string

The name of the service account.

Body

add_to_groupsarray of string

Adds the user or service account to the groups (specified by their names).

itemsstring

remove_from_groupsarray of string

Removes the user or service account from the groups (specified by their names). If a group is specified in both add_to_groups as well in here, removal wins.

itemsstring

set_groupsarray of string

itemsstring

Response

Service account groups membership updated successfully.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

user_count*integer

Is set to the number of users in this group.

sa_count*integer

Is set to the number of service accounts in this group.

role_count*integer

Is set to the number of roles associated with this group.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Returns all roles.

GEThttps://api.example.com/api/v1/roles

Response

Happy response.

Body

items*array of CompactRole (object)

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy_length*integer

Is set to the number of PermissionStatements in the Policy.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Creates a new role.

POSThttps://api.example.com/api/v1/roles

Body

name*string (hq-resource-name)

Sets the unique name of the new role. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring

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

policy*array of PermissionStatement (object)

Contains a list of permission statements.

action*PermissionActionScalarOrList (one of)

Is either a single action or a list of actions.

PermissionAction (enum)

Enumerates permission actions. This is an incomplete placeholder for illustration purposes.

kafka:ListTopicskafka:DeleteTopiciam:DeleteUser

resource*PermissionResourceScalarOrList (one of)

Is either a single string or a list of strings.

string

effect*PermissionEffect (enum)

Enumerates permission effects.

allowdeny

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Response

Happy response.

Body

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

action*PermissionActionScalarOrList (one of)

Is either a single action or a list of actions.

PermissionAction (enum)

Enumerates permission actions. This is an incomplete placeholder for illustration purposes.

kafka:ListTopicskafka:DeleteTopiciam:DeleteUser

resource*PermissionResourceScalarOrList (one of)

Is either a single string or a list of strings.

string

effect*PermissionEffect (enum)

Enumerates permission effects.

allowdeny

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Returns a specific role.

GEThttps://api.example.com/api/v1/roles/{name}

Path parameters

name*string

Response

Happy response.

Body

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

action*PermissionActionScalarOrList (one of)

Is either a single action or a list of actions.

PermissionAction (enum)

Enumerates permission actions. This is an incomplete placeholder for illustration purposes.

kafka:ListTopicskafka:DeleteTopiciam:DeleteUser

resource*PermissionResourceScalarOrList (one of)

Is either a single string or a list of strings.

string

effect*PermissionEffect (enum)

Enumerates permission effects.

allowdeny

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Updates a role.

PATCHhttps://api.example.com/api/v1/roles/{name}

Path parameters

name*string

Body

display_namestring

Updates the display name of the role.

policyarray of PermissionStatement (object)

Sets, if specififed, the new permission statements.

action*PermissionActionScalarOrList (one of)

Is either a single action or a list of actions.

PermissionAction (enum)

Enumerates permission actions. This is an incomplete placeholder for illustration purposes.

kafka:ListTopicskafka:DeleteTopiciam:DeleteUser

resource*PermissionResourceScalarOrList (one of)

Is either a single string or a list of strings.

string

effect*PermissionEffect (enum)

Enumerates permission effects.

allowdeny

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Other propertiesnullable string

Response

Happy response.

Body

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

action*PermissionActionScalarOrList (one of)

Is either a single action or a list of actions.

PermissionAction (enum)

Enumerates permission actions. This is an incomplete placeholder for illustration purposes.

kafka:ListTopicskafka:DeleteTopiciam:DeleteUser

resource*PermissionResourceScalarOrList (one of)

Is either a single string or a list of strings.

string

effect*PermissionEffect (enum)

Enumerates permission effects.

allowdeny

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Deletes a role.

DELETEhttps://api.example.com/api/v1/roles/{name}

Path parameters

name*string

Response

Successful deletion.

Request

Response

Returns the backend's meta information.

GEThttps://api.example.com/api/v1/meta-info

Response

Happy response.

Body

version*string

Is set to the HQ build version.

build_id*string

Is set to the HQ build id.

backend_build_id*string

Is set to the HQ backend build id.

ui_build_id*string

Is set to the HQ UI build id.

goos*string

Equals runtime.GOOS.

goarch*string

Equals runtime.GOARCH.

started_at*string (date-time)

Is set to the instant the backend started.

memstats_alloc*integer (int64)

Equals runtime.Memstats.Alloc.

memstats_sys*integer (int64)

Equals runtime.Memstats.Sys.

gc_cpu_fraction*number

Equals runtime.Memstats.GCCPUFraction.

num_goroutine*integer (int32)

Equals runtime.NumGoroutine().

Request

Response

Returns the backend's settings information.

GEThttps://api.example.com/api/v1/settings

Response

Successfully returns application settings response.

Body

api*APIConfig (object)

saml*SAMLConfig (object)

Contains SAML configuration settings.

user_creation_mode*Corresponds to user_creation_mode application config setting.

user_creation_mode setting controls how the creation of users should be handled in relation to SSO information. With the 'manual' mode, a user that exists externally in an Identity Provider will have to be manually created locally. With the 'sso' mode, that process will be automatic and a matching user will be created if it doesn't exist locally.

manualsso

users_group_membership_management_mode*Corresponds to users_group_membership_management_mode application config setting.

users_group_membership_management_mode setting controls how the management of a user's group membership should be handled in relation to SSO information. With the 'manual' mode, the information about the group membership returned from an Identity Provider will not be used and a user will only be a member of groups that were explicitly assigned to him locally. With the 'sso' mode, groups returned from Identity Provider will be used instead.

manualsso

Request

Response

Returns HQ's licence.

GEThttps://api.example.com/api/v1/licence

Response

Successfully returns licence response.

Body

expires_atstring (date-time)

Is set to the moment HQ no longer considers this licence valid. Will be omitted for licences that do not expire.

tier*LicenceTier (enum)

Enumerates licence tiers.

communityenterprise

Request

Response

Returns HQ's licence summary.

GEThttps://api.example.com/api/v1/licence-summary

Response

Successfully returns licence response.

Body

is_community*boolean

Is true when the licence is a community one, false otherwise.

Request

Response

Lists all environments

GEThttps://api.example.com/api/v1/environments

Response

Happy response.

Body

items*array of Environment (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

status*LiveEnvironmentInfo (object)

agent_connected*boolean

Signals whether an agent is currently connected.

agentLiveAgentInfo (object)

Is a collection of fields related to an agent. Updated only when an agent is connected.

updated_at*string (date-time)

Contains the time instant this object as a whole was updated.

roundtrip_duration*number (double)

Is measured in seconds.

agent*LensesAgentSummary (object)

Bundles licence info as gathered by the agent through Lenses' API.

hostname*string

Is set to the hostname of the machine the agent runs on.

version*string

Contains the version of the agent executable.

metricsAgentMetrics (object)

Bundles several categories of agent metrics.

kafkaAgentKafkaMetrics (object)

Is optionally part of AgentMetrics. Contains Kafka-specific metrics. Unavailable if Zoopeeker is not configured.

version*string

num_brokers*integer

updated_at*string (date-time)

data*AgentDataMetrics (object)

Is a part of AgentMetrics. Contains Data related metrics.

num_topics*integer

num_partitions*integer

num_schemas*integer

num_policies*integer

topic_data_total_bytesinteger (int64)

Is unavailable without Zookeeper. Total size of all topic data including replicas on disk [bytes].

data_in_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [bytes/s].

data_out_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data read from the brokers [bytes/s].

data_in_messages_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [msg/s].

updated_at*string (date-time)

apps*AgentAppsMetrics (object)

Is a part of AgentMetrics. Contains Apps metrics.

num_consumers*integer

num_other_apps*integer

updated_at*string (date-time)

connect*AgentConnectMetrics (object)

Is a part of AgentMetrics. Contains Kafka Connect metrics.

num_clusters*integer

num_connectors*integer

updated_at*string (date-time)

other*AgentOtherMetrics (object)

Is a part of AgentMetrics. Contains miscellaneous metrics.

num_issues*integer

updated_at*string (date-time)

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Updates an environment.

PATCHhttps://api.example.com/api/v1/environments/{name}

Path parameters

name*string

Body

tierTier (enum)

Enumerates Tiers.

developmentstagingproduction

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Other propertiesnullable string

display_namestring

Updates the display name of the environment.

Response

Happy response.

Body

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

status*LiveEnvironmentInfo (object)

agent_connected*boolean

Signals whether an agent is currently connected.

agentLiveAgentInfo (object)

Is a collection of fields related to an agent. Updated only when an agent is connected.

updated_at*string (date-time)

Contains the time instant this object as a whole was updated.

roundtrip_duration*number (double)

Is measured in seconds.

agent*LensesAgentSummary (object)

Bundles licence info as gathered by the agent through Lenses' API.

hostname*string

Is set to the hostname of the machine the agent runs on.

version*string

Contains the version of the agent executable.

metricsAgentMetrics (object)

Bundles several categories of agent metrics.

kafkaAgentKafkaMetrics (object)

Is optionally part of AgentMetrics. Contains Kafka-specific metrics. Unavailable if Zoopeeker is not configured.

version*string

num_brokers*integer

updated_at*string (date-time)

data*AgentDataMetrics (object)

Is a part of AgentMetrics. Contains Data related metrics.

num_topics*integer

num_partitions*integer

num_schemas*integer

num_policies*integer

topic_data_total_bytesinteger (int64)

Is unavailable without Zookeeper. Total size of all topic data including replicas on disk [bytes].

data_in_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [bytes/s].

data_out_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data read from the brokers [bytes/s].

data_in_messages_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [msg/s].

updated_at*string (date-time)

apps*AgentAppsMetrics (object)

Is a part of AgentMetrics. Contains Apps metrics.

num_consumers*integer

num_other_apps*integer

updated_at*string (date-time)

connect*AgentConnectMetrics (object)

Is a part of AgentMetrics. Contains Kafka Connect metrics.

num_clusters*integer

num_connectors*integer

updated_at*string (date-time)

other*AgentOtherMetrics (object)

Is a part of AgentMetrics. Contains miscellaneous metrics.

num_issues*integer

updated_at*string (date-time)

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Creates a new environment.

POSThttps://api.example.com/api/v1/environments

Body

name*string (hq-resource-name)

display_namestring

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

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Response

Happy response.

Body

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

status*LiveEnvironmentInfo (object)

agent_connected*boolean

Signals whether an agent is currently connected.

agentLiveAgentInfo (object)

Is a collection of fields related to an agent. Updated only when an agent is connected.

updated_at*string (date-time)

Contains the time instant this object as a whole was updated.

roundtrip_duration*number (double)

Is measured in seconds.

agent*LensesAgentSummary (object)

Bundles licence info as gathered by the agent through Lenses' API.

hostname*string

Is set to the hostname of the machine the agent runs on.

version*string

Contains the version of the agent executable.

metricsAgentMetrics (object)

Bundles several categories of agent metrics.

kafkaAgentKafkaMetrics (object)

Is optionally part of AgentMetrics. Contains Kafka-specific metrics. Unavailable if Zoopeeker is not configured.

version*string

num_brokers*integer

updated_at*string (date-time)

data*AgentDataMetrics (object)

Is a part of AgentMetrics. Contains Data related metrics.

num_topics*integer

num_partitions*integer

num_schemas*integer

num_policies*integer

topic_data_total_bytesinteger (int64)

Is unavailable without Zookeeper. Total size of all topic data including replicas on disk [bytes].

data_in_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [bytes/s].

data_out_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data read from the brokers [bytes/s].

data_in_messages_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [msg/s].

updated_at*string (date-time)

apps*AgentAppsMetrics (object)

Is a part of AgentMetrics. Contains Apps metrics.

num_consumers*integer

num_other_apps*integer

updated_at*string (date-time)

connect*AgentConnectMetrics (object)

Is a part of AgentMetrics. Contains Kafka Connect metrics.

num_clusters*integer

num_connectors*integer

updated_at*string (date-time)

other*AgentOtherMetrics (object)

Is a part of AgentMetrics. Contains miscellaneous metrics.

num_issues*integer

updated_at*string (date-time)

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

agent_key*string

Request

Response

Updates a group.

PATCHhttps://api.example.com/api/v1/groups/{name}

Path parameters

name*string

Body

display_namestring

Updates the display name of the group.

descriptionstring

Updates the Group description, if a value is provided.

rolesarray of string

Sets the Roles that are bound to this Group to the Roles (specified by their names), if provided.

itemsstring

add_membersarray of string

Adds the users/principals (specified by their names) to this group, if provided.

itemsstring

remove_membersarray of string

Removes the users/principals (specified by their names) from this group, if provided. If members are specified in both add_members as well in here, removal wins.

itemsstring

set_membersarray of string

Sets the members of this group to those users/principals (specified by their names) in an absolute fashion, if provided. Cannot be combined with the add_members or remove_members fields.

itemsstring

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Other propertiesnullable string

Response

Happy response.

Body

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy_length*integer

Is set to the number of PermissionStatements in the Policy.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

users*array of CompactUser (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

service_accounts*array of CompactServiceAccount (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Creates a new Group.

POSThttps://api.example.com/api/v1/groups

Body

name*string (hq-resource-name)

display_namestring

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

descriptionstring

Sets the description of the new group.

membersarray of string

Lists principal names (users, service accounts) to be member of this group.

itemsstring

rolesarray of string

Sets the Roles that are bound to this Group by name.

itemsstring

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Response

Happy response.

Body

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy_length*integer

Is set to the number of PermissionStatements in the Policy.

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

users*array of CompactUser (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

profile*UserProfile (object)

Models a user's Profile.

full_name*string

Contains the users' full name, e.g. Mary Jane Doe.

email_address*string

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

service_accounts*array of CompactServiceAccount (object)

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Retrieves a single environment by name.

GEThttps://api.example.com/api/v1/environments/{name}

Path parameters

name*string

Response

Happy response.

Body

name*string

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

tier*Tier (enum)

Enumerates Tiers.

developmentstagingproduction

status*LiveEnvironmentInfo (object)

agent_connected*boolean

Signals whether an agent is currently connected.

agentLiveAgentInfo (object)

Is a collection of fields related to an agent. Updated only when an agent is connected.

updated_at*string (date-time)

Contains the time instant this object as a whole was updated.

roundtrip_duration*number (double)

Is measured in seconds.

agent*LensesAgentSummary (object)

Bundles licence info as gathered by the agent through Lenses' API.

hostname*string

Is set to the hostname of the machine the agent runs on.

version*string

Contains the version of the agent executable.

metricsAgentMetrics (object)

Bundles several categories of agent metrics.

kafkaAgentKafkaMetrics (object)

Is optionally part of AgentMetrics. Contains Kafka-specific metrics. Unavailable if Zoopeeker is not configured.

version*string

num_brokers*integer

updated_at*string (date-time)

data*AgentDataMetrics (object)

Is a part of AgentMetrics. Contains Data related metrics.

num_topics*integer

num_partitions*integer

num_schemas*integer

num_policies*integer

topic_data_total_bytesinteger (int64)

Is unavailable without Zookeeper. Total size of all topic data including replicas on disk [bytes].

data_in_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [bytes/s].

data_out_bytes_per_secinteger (int64)

Is unavailable without Zookeeper. Data read from the brokers [bytes/s].

data_in_messages_per_secinteger (int64)

Is unavailable without Zookeeper. Data written to the brokers [msg/s].

updated_at*string (date-time)

apps*AgentAppsMetrics (object)

Is a part of AgentMetrics. Contains Apps metrics.

num_consumers*integer

num_other_apps*integer

updated_at*string (date-time)

connect*AgentConnectMetrics (object)

Is a part of AgentMetrics. Contains Kafka Connect metrics.

num_clusters*integer

num_connectors*integer

updated_at*string (date-time)

other*AgentOtherMetrics (object)

Is a part of AgentMetrics. Contains miscellaneous metrics.

num_issues*integer

updated_at*string (date-time)

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Other propertiesstring

Request

Response

Retrieves a list of datasets

GEThttps://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets

Path parameters

name*string

Query parameters

pageinteger

The page number to be returned, must be greater than zero. Defaults to 1.

Example: 1

pageSize*integer

The elements amount on a single page, must be greater than zero.

Example: 25

querystring

A search keyword to match dataset, fields and description against.

Example: "name"

connectionsarray of string

A list of connection names to filter by. All connections will be included when no value is supplied.

itemsstring

tagsarray of string

A list of tag names to filter by. All tags will be included when no value is supplied.

itemsstring

sortByDatasetField (enum)

The field to sort results by

sortingOrderOrder (enum)

Sorting order. Defaults to ascending

ascdesc

includeSystemEntitiesboolean

A flag to include in the search also system entities (e.g. Kafka's __consumer_offsets topic).

includeMetadataboolean

Whether to search only by table name, or also to include field names/documentation (defaults to true)

formatarray of string

Schema format. Relevant only when sourceType is SchemaRegistrySubject

itemsstring

hasRecordsboolean

Filter based on whether the dataset has records

compactedboolean

Filter based on compacted. Relevant only when sourceType is Kafka

Response

A response wrapping a paginated list of datasets and the set of relative source types

Body

datasets*Page_DatasetMatch (object)

valuesarray of Kafka (object)

name*string

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

recordsinteger (int64)

recordsPerSecond*integer (int64)

keyType*string

valueType*string

connectionName*string

replication*integer

consumers*integer

partitions*integer

fieldsFields (object)

keyarray of Field (object)

name*string

typestring

typeDetails*FieldTypeDetails (one of)

lensesDataType*string

descriptionstring

ancestorsarray of string

itemsstring

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

isNullable*boolean

defaultstring

valuearray of Field (object)

name*string

typestring

typeDetails*FieldTypeDetails (one of)

lensesDataType*string

descriptionstring

ancestorsarray of string

itemsstring

highlightsarray of Highlight (object)

fieldName*string

startIndex*integer

endIndex*integer

arrayIndex*integer

isNullable*boolean

defaultstring

isSystemEntity*boolean

isMarkedForDeletion*boolean

isCompacted*boolean

sizeBytesinteger (int64)

policiesarray of PolicyMatchDetails (object)

policyId*string

policyName*string

policyCategory*string

obfuscation*string

matchingKeyFieldsarray of PolicyFieldMatch (object)

name*string

parentsarray of string

itemsstring

matchingValueFieldsarray of PolicyFieldMatch (object)

name*string

parentsarray of string

itemsstring

permissions*array of string

itemsstring

descriptionstring

tagsarray of DatasetTag (object)

name*string

count*number

retentionMsinteger (int64)

retentionBytesinteger (int64)

backupRestoreStateBackupRestoreState (one of)

sourceType*string

pagesAmount*integer (int64)

totalCount*integer (int64)

sourceTypesarray of SourceType (enum)

itemsSourceType (enum)

KafkaElasticPostgresSchemaRegistrySubject

Request

Response