Home
ProductsDownload Community Edition

Environments

get

Lists all environments

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-26T10:21:23.119Z",
      "tier": "development",
      "status": {
        "agent_connected": true,
        "agent": {
          "updated_at": "2025-03-26T10:21:23.119Z",
          "roundtrip_duration": 1,
          "agent": {
            "hostname": "text",
            "version": "text"
          },
          "metrics": {
            "kafka": {
              "version": "text",
              "num_brokers": 1,
              "updated_at": "2025-03-26T10:21:23.119Z"
            },
            "data": {
              "num_topics": 1,
              "num_partitions": 1,
              "num_schemas": 1,
              "num_policies": 1,
              "topic_data_total_bytes": 1,
              "data_in_bytes_per_sec": 1,
              "data_out_bytes_per_sec": 1,
              "data_in_messages_per_sec": 1,
              "updated_at": "2025-03-26T10:21:23.119Z"
            },
            "apps": {
              "num_consumers": 1,
              "num_other_apps": 1,
              "updated_at": "2025-03-26T10:21:23.119Z"
            },
            "connect": {
              "num_clusters": 1,
              "num_connectors": 1,
              "updated_at": "2025-03-26T10:21:23.119Z"
            },
            "other": {
              "num_issues": 1,
              "updated_at": "2025-03-26T10:21:23.119Z"
            }
          }
        }
      },
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

post

Creates a new environment.

Authorizations
Body
namestring · hq-resource-name · min: 1 · max: 63required

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

display_namestring · min: 1 · max: 150optional

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

tierstring · enumrequired

Enumerates Tiers.

Options: development, staging, production
metadataobjectoptional

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

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

Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/environments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "tier": "development",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-26T10:21:23.119Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-03-26T10:21:23.119Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "data": {
          "num_topics": 1,
          "num_partitions": 1,
          "num_schemas": 1,
          "num_policies": 1,
          "topic_data_total_bytes": 1,
          "data_in_bytes_per_sec": 1,
          "data_out_bytes_per_sec": 1,
          "data_in_messages_per_sec": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "agent_key": "text"
}

Happy response.

get

Retrieves a single environment by name.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-26T10:21:23.119Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-03-26T10:21:23.119Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "data": {
          "num_topics": 1,
          "num_partitions": 1,
          "num_schemas": 1,
          "num_policies": 1,
          "topic_data_total_bytes": 1,
          "data_in_bytes_per_sec": 1,
          "data_out_bytes_per_sec": 1,
          "data_in_messages_per_sec": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

patch

Updates an environment.

Authorizations
Path parameters
namestringrequired
Body
tierstring · enumoptional

Enumerates Tiers.

Options: development, staging, production
metadataobjectoptional

Patches metadata. It has the following semantics:

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

display_namestring · min: 1 · max: 150optional

Updates the display name of the environment.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/environments/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "tier": "development",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "display_name": "text"
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-26T10:21:23.119Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-03-26T10:21:23.119Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "data": {
          "num_topics": 1,
          "num_partitions": 1,
          "num_schemas": 1,
          "num_policies": 1,
          "topic_data_total_bytes": 1,
          "data_in_bytes_per_sec": 1,
          "data_out_bytes_per_sec": 1,
          "data_in_messages_per_sec": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-03-26T10:21:23.119Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

delete

Deletes an environment.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/environments/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Successful deletion.

get

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

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/live/sse' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "type": "not_found",
  "title": "text",
  "status": 1,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}

Error object.

get

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

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "type": "not_found",
  "title": "text",
  "status": 1,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}

Error object.

get

Retrieves a list of datasets

Authorizations
Path parameters
namestringrequired
Query parameters
pageintegeroptional

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

Example: 1
pageSizeintegerrequired

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

Example: 25
querystringoptional

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

Example: name
connectionsstring[]optional

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

tagsstring[]optional

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

sortBystring · enumoptional

The field to sort results by

Options: name, records, connectionName, sourceType, isSystemEntity, recordsPerSecond, keyType, valueType, replication, consumers, partitions, retentionBytes, retentionMs, sizeBytes, replicas, shard, version, format, compatibility, backupRestoreState
sortingOrderstring · enumoptional

Sorting order. Defaults to ascending

Options: asc, desc
includeSystemEntitiesbooleanoptional

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

includeMetadatabooleanoptional

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

formatstring[]optional

Schema format. Relevant only when sourceType is SchemaRegistrySubject

hasRecordsbooleanoptional

Filter based on whether the dataset has records

compactedbooleanoptional

Filter based on compacted. Relevant only when sourceType is Kafka

Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets?pageSize=1' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "datasets": {
    "values": [
      {
        "name": "text",
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "records": 1,
        "recordsPerSecond": 1,
        "keyType": "text",
        "valueType": "text",
        "connectionName": "text",
        "replication": 1,
        "consumers": 1,
        "partitions": 1,
        "fields": {
          "key": [
            {
              "name": "text",
              "type": "text",
              "typeDetails": {
                "lensesDataType": "text"
              },
              "description": "text",
              "ancestors": [
                "text"
              ],
              "highlights": [
                {
                  "fieldName": "text",
                  "startIndex": 1,
                  "endIndex": 1,
                  "arrayIndex": 1
                }
              ],
              "isNullable": true,
              "default": "text"
            }
          ],
          "value": [
            {
              "name": "text",
              "type": "text",
              "typeDetails": {
                "lensesDataType": "text"
              },
              "description": "text",
              "ancestors": [
                "text"
              ],
              "highlights": [
                {
                  "fieldName": "text",
                  "startIndex": 1,
                  "endIndex": 1,
                  "arrayIndex": 1
                }
              ],
              "isNullable": true,
              "default": "text"
            }
          ]
        },
        "isSystemEntity": true,
        "isMarkedForDeletion": true,
        "isCompacted": true,
        "sizeBytes": 1,
        "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": 1
          }
        ],
        "retentionMs": 1,
        "retentionBytes": 1,
        "backupRestoreState": {},
        "sourceType": "text"
      }
    ],
    "pagesAmount": 1,
    "totalCount": 1
  },
  "sourceTypes": [
    "Kafka"
  ]
}

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

get

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

Authorizations
Path parameters
namestringrequired
connectionstringrequired
Example: kafka
datasetstringrequired
Example: customer-positions
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/{connection}/{dataset}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "highlights": [
    {
      "fieldName": "text",
      "startIndex": 1,
      "endIndex": 1,
      "arrayIndex": 1
    }
  ],
  "records": 1,
  "recordsPerSecond": 1,
  "keyType": "text",
  "valueType": "text",
  "connectionName": "text",
  "replication": 1,
  "consumers": 1,
  "partitions": 1,
  "fields": {
    "key": [
      {
        "name": "text",
        "type": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "isNullable": true,
        "default": "text"
      }
    ],
    "value": [
      {
        "name": "text",
        "type": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "isNullable": true,
        "default": "text"
      }
    ]
  },
  "isSystemEntity": true,
  "isMarkedForDeletion": true,
  "isCompacted": true,
  "sizeBytes": 1,
  "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": 1
    }
  ],
  "retentionMs": 1,
  "retentionBytes": 1,
  "backupRestoreState": {},
  "sourceType": "text"
}
get

Retrieves a list of dataset tags

Authorizations
Path parameters
namestringrequired
Query parameters
querystringoptional

Get tags sorted by dataset count

Example: user
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/tags' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "tags": [
    {
      "name": "text",
      "count": 1
    }
  ]
}

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

post

Returns the intellisense result for a given query

Authorizations
Path parameters
namestringrequired
Body
sqlstringrequired
caretintegeroptional
connectorIdstringoptional
Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/sql/presentation' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "sql": "text",
    "caret": 1,
    "connectorId": "text"
  }'
{
  "input": "text",
  "caret": 1,
  "lints": [
    {
      "start": 1,
      "end": 1,
      "text": "text",
      "type": "Warning"
    }
  ],
  "suggestions": [
    {
      "display": "text",
      "text": "text",
      "start": 1,
      "end": 1,
      "type": "text",
      "description": "text",
      "highlightStart": 1,
      "highlightEnd": 1
    }
  ],
  "highlights": [
    {
      "start": 1,
      "end": 1,
      "text": "text",
      "type": "Keyword"
    }
  ],
  "tables": [
    {
      "tableName": {
        "value": "text"
      },
      "fields": [
        {
          "value": "text"
        }
      ]
    }
  ],
  "statementsPositions": [
    {
      "index": 1,
      "start": 1,
      "end": 1
    }
  ]
}

Happy response

PreviousService AccountsNextLicense

Last updated

Was this helpful?