Environments

Lists all environments

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

Response

200default

Happy response.

Body

application/json

items*array of Environment (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:01:53.711Z",
      "tier": "development",
      "status": {
        "agent_connected": false,
        "agent": {
          "updated_at": "2025-01-17T06:01:53.711Z",
          "roundtrip_duration": 0,
          "agent": {
            "hostname": "text",
            "version": "text"
          },
          "metrics": {
            "kafka": {
              "version": "text",
              "num_brokers": 0,
              "updated_at": "2025-01-17T06:01:53.711Z"
            },
            "data": {
              "num_topics": 0,
              "num_partitions": 0,
              "num_schemas": 0,
              "num_policies": 0,
              "topic_data_total_bytes": 0,
              "data_in_bytes_per_sec": 0,
              "data_out_bytes_per_sec": 0,
              "data_in_messages_per_sec": 0,
              "updated_at": "2025-01-17T06:01:53.711Z"
            },
            "apps": {
              "num_consumers": 0,
              "num_other_apps": 0,
              "updated_at": "2025-01-17T06:01:53.711Z"
            },
            "connect": {
              "num_clusters": 0,
              "num_connectors": 0,
              "updated_at": "2025-01-17T06:01:53.711Z"
            },
            "other": {
              "num_issues": 0,
              "updated_at": "2025-01-17T06:01:53.711Z"
            }
          }
        }
      }
    }
  ]
}

Creates a new environment.

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

Body

application/json

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.

Response

201default

Happy response.

Body

application/json

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.

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.

agent_key*string

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "tier": "development"
    }),
});
const data = await response.json();

Response

201default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:01:53.711Z",
  "tier": "development",
  "status": {
    "agent_connected": false,
    "agent": {
      "updated_at": "2025-01-17T06:01:53.711Z",
      "roundtrip_duration": 0,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "data": {
          "num_topics": 0,
          "num_partitions": 0,
          "num_schemas": 0,
          "num_policies": 0,
          "topic_data_total_bytes": 0,
          "data_in_bytes_per_sec": 0,
          "data_out_bytes_per_sec": 0,
          "data_in_messages_per_sec": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "apps": {
          "num_consumers": 0,
          "num_other_apps": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "connect": {
          "num_clusters": 0,
          "num_connectors": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "other": {
          "num_issues": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        }
      }
    }
  },
  "agent_key": "text"
}

Retrieves a single environment by name.

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

Path parameters

name*string

Response

200default

Happy response.

Body

application/json

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.

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.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/{name}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:01:53.711Z",
  "tier": "development",
  "status": {
    "agent_connected": false,
    "agent": {
      "updated_at": "2025-01-17T06:01:53.711Z",
      "roundtrip_duration": 0,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "data": {
          "num_topics": 0,
          "num_partitions": 0,
          "num_schemas": 0,
          "num_policies": 0,
          "topic_data_total_bytes": 0,
          "data_in_bytes_per_sec": 0,
          "data_out_bytes_per_sec": 0,
          "data_in_messages_per_sec": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "apps": {
          "num_consumers": 0,
          "num_other_apps": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "connect": {
          "num_clusters": 0,
          "num_connectors": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "other": {
          "num_issues": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        }
      }
    }
  }
}

Updates an environment.

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

Path parameters

name*string

Body

application/json

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.

display_namestring

Updates the display name of the environment.

Response

200default

Happy response.

Body

application/json

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.

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.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/{name}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:01:53.711Z",
  "tier": "development",
  "status": {
    "agent_connected": false,
    "agent": {
      "updated_at": "2025-01-17T06:01:53.711Z",
      "roundtrip_duration": 0,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "data": {
          "num_topics": 0,
          "num_partitions": 0,
          "num_schemas": 0,
          "num_policies": 0,
          "topic_data_total_bytes": 0,
          "data_in_bytes_per_sec": 0,
          "data_out_bytes_per_sec": 0,
          "data_in_messages_per_sec": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "apps": {
          "num_consumers": 0,
          "num_other_apps": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "connect": {
          "num_clusters": 0,
          "num_connectors": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        },
        "other": {
          "num_issues": 0,
          "updated_at": "2025-01-17T06:01:53.711Z"
        }
      }
    }
  }
}

Deletes an environment.

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

Path parameters

name*string

Response

204default

Successful deletion.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/{name}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

default

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

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

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

Response

default

Error object.

Body

application/json

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.

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

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/live/sse', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

default

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

Proxies HTTP to a Lenses instance. Note: this is not a regular HTTP API endpoint. The path specified here is a prefix. Everything beneath it gets proxied to the corresponding Lenses instance. Any request body and method (the GET here is only a placeholder) are accepted, as long as the Lenses API accepts it. The connection can even be upgraded to a websocket. The status code and response body are controlled by the Lenses API. This concept does not fit into the OpenAPI world at all; this definition is only here for the sake of documentation to avoid having an undocumented dark matter API.

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

Path parameters

name*string

Response

default

Error object.

Body

application/json

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.

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

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/{name}/proxy/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

default

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

Retrieves a list of datasets

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

Path parameters

name*string

Query parameters

Response

200400401402403404500

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

Body

application/json

datasets*Page_DatasetMatch (object)

sourceTypesarray of SourceType (enum)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets?pageSize=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401402403404500

{
  "datasets": {
    "values": [
      {
        "name": "text",
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 0,
            "endIndex": 0,
            "arrayIndex": 0
          }
        ],
        "records": 0,
        "recordsPerSecond": 0,
        "keyType": "text",
        "valueType": "text",
        "connectionName": "text",
        "replication": 0,
        "consumers": 0,
        "partitions": 0,
        "fields": {
          "key": [
            {
              "name": "text",
              "type": "text",
              "typeDetails": {
                "lensesDataType": "text"
              },
              "description": "text",
              "ancestors": [
                "text"
              ],
              "highlights": [
                {
                  "fieldName": "text",
                  "startIndex": 0,
                  "endIndex": 0,
                  "arrayIndex": 0
                }
              ],
              "isNullable": false,
              "default": "text"
            }
          ],
          "value": [
            {
              "name": "text",
              "type": "text",
              "typeDetails": {
                "lensesDataType": "text"
              },
              "description": "text",
              "ancestors": [
                "text"
              ],
              "highlights": [
                {
                  "fieldName": "text",
                  "startIndex": 0,
                  "endIndex": 0,
                  "arrayIndex": 0
                }
              ],
              "isNullable": false,
              "default": "text"
            }
          ]
        },
        "isSystemEntity": false,
        "isMarkedForDeletion": false,
        "isCompacted": false,
        "sizeBytes": 0,
        "policies": [
          {
            "policyId": "text",
            "policyName": "text",
            "policyCategory": "text",
            "obfuscation": "text",
            "matchingKeyFields": [
              {
                "name": "text",
                "parents": [
                  "text"
                ]
              }
            ],
            "matchingValueFields": [
              {
                "name": "text",
                "parents": [
                  "text"
                ]
              }
            ]
          }
        ],
        "permissions": [
          "text"
        ],
        "description": "text",
        "tags": [
          {
            "name": "text",
            "count": 0
          }
        ],
        "retentionMs": 0,
        "retentionBytes": 0,
        "sourceType": "text"
      }
    ],
    "pagesAmount": 0,
    "totalCount": 0
  },
  "sourceTypes": [
    "Kafka"
  ]
}

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

200400401402403404500

Body

application/json

DatasetMatch (one of)

Kafka (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/{connection}/{dataset}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401402403404500

{
  "name": "text",
  "highlights": [
    {
      "fieldName": "text",
      "startIndex": 0,
      "endIndex": 0,
      "arrayIndex": 0
    }
  ],
  "records": 0,
  "recordsPerSecond": 0,
  "keyType": "text",
  "valueType": "text",
  "connectionName": "text",
  "replication": 0,
  "consumers": 0,
  "partitions": 0,
  "fields": {
    "key": [
      {
        "name": "text",
        "type": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 0,
            "endIndex": 0,
            "arrayIndex": 0
          }
        ],
        "isNullable": false,
        "default": "text"
      }
    ],
    "value": [
      {
        "name": "text",
        "type": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 0,
            "endIndex": 0,
            "arrayIndex": 0
          }
        ],
        "isNullable": false,
        "default": "text"
      }
    ]
  },
  "isSystemEntity": false,
  "isMarkedForDeletion": false,
  "isCompacted": false,
  "sizeBytes": 0,
  "policies": [
    {
      "policyId": "text",
      "policyName": "text",
      "policyCategory": "text",
      "obfuscation": "text",
      "matchingKeyFields": [
        {
          "name": "text",
          "parents": [
            "text"
          ]
        }
      ],
      "matchingValueFields": [
        {
          "name": "text",
          "parents": [
            "text"
          ]
        }
      ]
    }
  ],
  "permissions": [
    "text"
  ],
  "description": "text",
  "tags": [
    {
      "name": "text",
      "count": 0
    }
  ],
  "retentionMs": 0,
  "retentionBytes": 0,
  "sourceType": "text"
}

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

Response

200400401402403404500

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

Body

application/json

tags*array of DatasetTag (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/tags', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401402403404500

{
  "tags": [
    {
      "name": "text",
      "count": 0
    }
  ]
}

Returns the intellisense result for a given query

POSThttps://api.example.com/api/v1/environments/{name}/proxy/api/v1/sql/presentation

Path parameters

name*string

Body

application/json

sql*string

caretinteger

connectorIdstring

Response

200400401402403404500default

Happy response

Body

application/json

input*string

caret*integer

lintsarray of Lint (object)

suggestionsarray of Suggestion (object)

highlightsarray of Highlight1 (object)

tablesarray of TableFields (object)

statementsPositionsarray of StatementPos (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/environments/{name}/proxy/api/v1/sql/presentation', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "sql": "text"
    }),
});
const data = await response.json();

Response

200400401402403404500default

{
  "input": "text",
  "caret": 0,
  "lints": [
    {
      "start": 0,
      "end": 0,
      "text": "text",
      "type": "Warning"
    }
  ],
  "suggestions": [
    {
      "display": "text",
      "text": "text",
      "start": 0,
      "end": 0,
      "type": "text",
      "description": "text",
      "highlightStart": 0,
      "highlightEnd": 0
    }
  ],
  "highlights": [
    {
      "start": 0,
      "end": 0,
      "text": "text",
      "type": "Keyword"
    }
  ],
  "tables": [
    {
      "tableName": {
        "value": "text"
      },
      "fields": [
        {
          "value": "text"
        }
      ]
    }
  ],
  "statementsPositions": [
    {
      "index": 0,
      "start": 0,
      "end": 0
    }
  ]
}