Topics | Lenses Docs

Products Download Community Edition

Deprecated

get

Retrieve information about all topics

Responses

application/json

object[]Optional

application/json

get

GET /api/v1/environments/{name}/proxy/api/topics HTTP/1.1
Host: 
Accept: */*

[
  {
    "topicName": "text",
    "partitions": 1,
    "replication": 1,
    "isControlTopic": true,
    "isCompacted": true,
    "keyType": "text",
    "valueType": "text",
    "totalMessages": 1,
    "config": [
      {
        "name": "text",
        "value": "text",
        "isDefault": true,
        "defaultValue": "text",
        "documentation": "text",
        "originalValue": "text"
      }
    ],
    "consumers": [
      {
        "id": "text",
        "coordinator": {
          "id": 1,
          "host": "text",
          "port": 1,
          "rack": "text"
        },
        "active": true,
        "state": "Unknown",
        "consumers": [
          "text"
        ],
        "consumersCount": 1,
        "topicPartitionsCount": 1,
        "minLag": 1,
        "maxLag": 1,
        "application": {
          "id": "text",
          "name": "text",
          "type": "AkkaStreams"
        }
      }
    ],
    "messagesPerPartition": [
      {
        "partition": 1,
        "messages": 1,
        "begin": 1,
        "end": 1
      }
    ],
    "messagesPerSecond": 1,
    "isMarkedForDeletion": true,
    "timestamp": 1,
    "keySchema": "text",
    "keySchemaVersion": 1,
    "keySchemaInlined": "text",
    "valueSchema": "text",
    "valueSchemaVersion": 1,
    "valueSchemaInlined": "text",
    "applications": [
      {
        "id": "text",
        "name": "text",
        "type": "AkkaStreams"
      }
    ],
    "description": "text",
    "tags": [
      {
        "name": "text"
      }
    ],
    "permissions": [
      "text"
    ],
    "backups": [
      {
        "id": 1,
        "createdAt": "2025-04-19T17:23:43.268Z",
        "topic": "text",
        "connectCluster": "text",
        "connectorName": "text",
        "connectorVersion": "text",
        "s3Location": "text",
        "reference": "text"
      }
    ],
    "restores": [
      {
        "id": 1,
        "createdAt": "2025-04-19T17:23:43.268Z",
        "topic": "text",
        "connectCluster": "text",
        "connectorName": "text",
        "connectorVersion": "text",
        "s3Location": "text",
        "reference": "text"
      }
    ]
  }
]

Deprecated

get

Retrieve a given topic partition details

Path parameters

p1stringRequired

Name of the topic

Responses

application/json

object[]Optional

text/plain

get

GET /api/v1/environments/{name}/proxy/api/topics/{p1}/partitions HTTP/1.1
Host: 
Accept: */*

[
  {
    "partition": 1,
    "leader": 1,
    "preferredLeader": 1,
    "replicas": [
      {
        "broker": 1,
        "leader": true,
        "inSync": true
      }
    ]
  }
]

Deprecated

get

Retrieve information about a given topic

Path parameters

p1stringRequired

Name of the topic

Responses

application/json

objectOptional

text/plain

get

GET /api/v1/environments/{name}/proxy/api/topics/{p1} HTTP/1.1
Host: 
Accept: */*

{
  "topicName": "text",
  "partitions": 1,
  "replication": 1,
  "isControlTopic": true,
  "isCompacted": true,
  "keyType": "text",
  "valueType": "text",
  "totalMessages": 1,
  "config": [
    {
      "name": "text",
      "value": "text",
      "isDefault": true,
      "defaultValue": "text",
      "documentation": "text",
      "originalValue": "text"
    }
  ],
  "consumers": [
    {
      "id": "text",
      "coordinator": {
        "id": 1,
        "host": "text",
        "port": 1,
        "rack": "text"
      },
      "active": true,
      "state": "Unknown",
      "consumers": [
        "text"
      ],
      "consumersCount": 1,
      "topicPartitionsCount": 1,
      "minLag": 1,
      "maxLag": 1,
      "application": {
        "id": "text",
        "name": "text",
        "type": "AkkaStreams"
      }
    }
  ],
  "messagesPerPartition": [
    {
      "partition": 1,
      "messages": 1,
      "begin": 1,
      "end": 1
    }
  ],
  "messagesPerSecond": 1,
  "isMarkedForDeletion": true,
  "timestamp": 1,
  "keySchema": "text",
  "keySchemaVersion": 1,
  "keySchemaInlined": "text",
  "valueSchema": "text",
  "valueSchemaVersion": 1,
  "valueSchemaInlined": "text",
  "applications": [
    {
      "id": "text",
      "name": "text",
      "type": "AkkaStreams"
    }
  ],
  "description": "text",
  "tags": [
    {
      "name": "text"
    }
  ],
  "permissions": [
    "text"
  ],
  "backups": [
    {
      "id": 1,
      "createdAt": "2025-04-19T17:23:43.268Z",
      "topic": "text",
      "connectCluster": "text",
      "connectorName": "text",
      "connectorVersion": "text",
      "s3Location": "text",
      "reference": "text"
    }
  ],
  "restores": [
    {
      "id": 1,
      "createdAt": "2025-04-19T17:23:43.268Z",
      "topic": "text",
      "connectCluster": "text",
      "connectorName": "text",
      "connectorVersion": "text",
      "s3Location": "text",
      "reference": "text"
    }
  ]
}

Deprecated

get

Path parameters

topicstringRequired

The topic name

Responses

application/json

object[]Optional

text/plain

get

GET /api/v1/environments/{name}/proxy/api/topics/{topic}/brokerConfigs HTTP/1.1
Host: 
Accept: */*

[
  {
    "name": "text",
    "value": "text",
    "isDefault": true,
    "isSensitive": true,
    "isReadOnly": true
  }
]

get

Retrieve information about partitions of a given topic

Path parameters

topicstringRequired

Name of the topic

Responses

application/json

objectOptional

application/json

get

GET /api/v1/environments/{name}/proxy/api/v2/topics/{topic}/partitions HTTP/1.1
Host: 
Accept: */*

{
  "partitions": [
    {
      "partition": 1,
      "leader": 1,
      "preferredLeader": 1,
      "messages": 1,
      "begin": 1,
      "end": 1,
      "bytes": 1,
      "replicas": [
        {
          "broker": 1,
          "leader": true,
          "inSync": true
        }
      ]
    }
  ],
  "jmxLastRetrievedAt": "2025-04-19T17:23:43.268Z"
}

put

Resend a kafka message

Path parameters

topicstringRequired

Name of the topic

partitionintegerRequired

Kafka partition

offsetinteger · int64Required

Kafka offset

Responses

application/json

objectOptional

application/json

put

PUT /api/v1/environments/{name}/proxy/api/topics/{topic}/{partition}/{offset}/resend HTTP/1.1
Host: 
Accept: */*

{
  "partition": 1,
  "offset": 1
}

delete

Path parameters

topicNamestringRequired

partitionintegerRequired

offsetinteger · int64Required

Responses

application/json

stringOptional

text/plain

delete

DELETE /api/v1/environments/{name}/proxy/api/topics/{topicName}/{partition}/{offset} HTTP/1.1
Host: 
Accept: */*

text

delete

Path parameters

topicNamestringRequired

Responses

application/json

stringOptional

text/plain

delete

DELETE /api/v1/environments/{name}/proxy/api/topics/{topicName} HTTP/1.1
Host: 
Accept: */*

text

Deprecated

get

Deprecated. To fetch Kafka topic details, please, use (listDatasets) /api/v1/environments/{name}/proxy/api/v1/datasets.

Responses

application/json

object[]Optional

application/json

get

GET /api/v1/environments/{name}/proxy/api/v1/kafka/topics HTTP/1.1
Host: 
Accept: */*

[
  {
    "topicName": "text",
    "partitions": 1,
    "replication": 1,
    "isControlTopic": true,
    "keyType": "text",
    "valueType": "text",
    "totalMessages": 1,
    "configs": 1,
    "consumers": 1,
    "messagesPerSecond": 1,
    "isMarkedForDeletion": true,
    "isCompacted": true,
    "description": "text",
    "tags": [
      {
        "name": "text"
      }
    ],
    "permissions": [
      "text"
    ]
  }
]

Deprecated

get

Deprecated. To fetch Kafka topic details, please, use (listDatasets) /api/v1/environments/{name}/proxy/api/v1/datasets.

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

sortBystring · enumOptional

The field to sort results by

Available options:

sortingOrderstring · enumOptional

Sorting order. Defaults to ascending

Available options:

namestringOptional

Filter by topic name

includeSystemTopicsbooleanOptional

Responses

application/json

objectOptional

application/json

get

GET /api/v1/environments/{name}/proxy/api/v2/kafka/topics?pageSize=1 HTTP/1.1
Host: 
Accept: */*

{
  "topics": [
    {
      "topicName": "text",
      "partitions": 1,
      "replication": 1,
      "isControlTopic": true,
      "keyType": "text",
      "valueType": "text",
      "totalMessages": 1,
      "configs": 1,
      "consumers": 1,
      "messagesPerSecond": 1,
      "isMarkedForDeletion": true,
      "isCompacted": true,
      "description": "text",
      "tags": [
        {
          "name": "text"
        }
      ],
      "permissions": [
        "text"
      ]
    }
  ],
  "pageCount": 1,
  "totalTopicCount": 1
}

get

Path parameters

topicNamestringRequired

Kafka Topic name

Responses

application/json

objectOptional

application/json

get

GET /api/v1/environments/{name}/proxy/api/metadata/topics/{topicName} HTTP/1.1
Host: 
Accept: */*

{
  "topicName": "text",
  "keyType": "text",
  "valueType": "text",
  "keySchema": "text",
  "keySchemaVersion": 1,
  "keySchemaInlined": "text",
  "valueSchema": "text",
  "valueSchemaVersion": 1,
  "valueSchemaInlined": "text",
  "description": "text",
  "tags": [
    "text"
  ],
  "additionalInfo": null
}

delete

Path parameters

topicNamestringRequired

The topic name

Responses

application/json

delete

DELETE /api/v1/environments/{name}/proxy/api/metadata/topics/{topicName} HTTP/1.1
Host: 
Accept: */*

No content

get

Responses

application/json

object[]Optional

application/json

get

GET /api/v1/environments/{name}/proxy/api/metadata/topics HTTP/1.1
Host: 
Accept: */*

[
  {
    "topicName": "text",
    "keyType": "text",
    "valueType": "text",
    "keySchema": "text",
    "keySchemaVersion": 1,
    "keySchemaInlined": "text",
    "valueSchema": "text",
    "valueSchemaVersion": 1,
    "valueSchemaInlined": "text",
    "description": "text",
    "tags": [
      "text"
    ],
    "additionalInfo": null
  }
]

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

Path parameters

connectionstringRequiredExample: kafka

datasetstringRequiredExample: customer-positions

Responses

application/json

one ofOptional

application/json

get

GET /api/v1/environments/{name}/proxy/api/v1/datasets/{connection}/{dataset} HTTP/1.1
Host: 
Accept: */*

{
  "name": "text",
  "highlights": [
    {
      "fieldName": "text",
      "startIndex": 1,
      "endIndex": 1,
      "arrayIndex": 1
    }
  ],
  "sizeBytes": 1,
  "records": 1,
  "connectionName": "text",
  "replicas": 1,
  "shard": 1,
  "fields": {
    "key": [
      {
        "name": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "isNullable": true,
        "default": "text"
      }
    ],
    "value": [
      {
        "name": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "isNullable": true,
        "default": "text"
      }
    ]
  },
  "isSystemEntity": true,
  "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"
    }
  ],
  "sourceType": "text"
}

get

get ranged metrics for requested dataset

Path parameters

entityNamestringRequired

Dataset's entity name

Example: topic

Responses

application/json

object[]Optional

text/plain

get

GET /api/v1/environments/{name}/proxy/api/v1/datasets/kafka/{entityName}/messages/metrics HTTP/1.1
Host: 
Accept: */*

[
  {
    "date": "2025-04-19T17:23:43.268Z",
    "messagesCount": 1
  }
]

get

Retrieves a list of datasets

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

Available options:

sortingOrderstring · enumOptional

Sorting order. Defaults to ascending

Available options:

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

application/json

objectOptional

application/json

get

GET /api/v1/environments/{name}/proxy/api/v1/datasets?pageSize=1 HTTP/1.1
Host: 
Accept: */*

{
  "datasets": {
    "values": [
      {
        "name": "telecom_italia",
        "highlights": [],
        "records": 80000000,
        "recordsPerSecond": 1813,
        "keyType": "AVRO",
        "valueType": "AVRO",
        "connectionName": "Kafka",
        "replication": 1,
        "consumers": 0,
        "partitions": 6,
        "fields": {
          "key": [],
          "value": [
            {
              "type": "STRING",
              "name": "name",
              "typeDetails": {
                "lensesDataType": "STRING",
                "kind": "Lenses"
              },
              "ancestors": [],
              "highlights": [
                {
                  "fieldName": "name",
                  "startIndex": 1,
                  "endIndex": 5,
                  "arrayIndex": 0
                }
              ],
              "isNullable": false
            }
          ]
        },
        "isSystemEntity": false,
        "isMarkedForDeletion": false,
        "isCompacted": false,
        "sizeBytes": 25,
        "policies": [],
        "permissions": [
          "ShowTopic"
        ],
        "tags": [],
        "retentionMs": 604800000,
        "retentionBytes": 1073741824,
        "backupRestoreState": "backup-restore",
        "sourceType": "Kafka"
      },
      {
        "name": "bank",
        "highlights": [],
        "sizeBytes": 487000,
        "records": 1000,
        "connectionName": "es6b",
        "replicas": 5,
        "shard": 5,
        "fields": {
          "key": [],
          "value": [
            {
              "type": "STRING",
              "name": "firstname",
              "typeDetails": {
                "lensesDataType": "STRING",
                "kind": "Lenses"
              },
              "description": "The customer first name",
              "ancestors": [],
              "highlights": [
                {
                  "fieldName": "name",
                  "startIndex": 5,
                  "endIndex": 9,
                  "arrayIndex": 0
                },
                {
                  "fieldName": "description",
                  "startIndex": 18,
                  "endIndex": 22,
                  "arrayIndex": 0
                }
              ],
              "isNullable": false
            },
            {
              "type": "STRING",
              "name": "lastname",
              "typeDetails": {
                "lensesDataType": "STRING",
                "kind": "Lenses"
              },
              "ancestors": [],
              "highlights": [
                {
                  "fieldName": "name",
                  "startIndex": 4,
                  "endIndex": 8,
                  "arrayIndex": 0
                }
              ],
              "isNullable": false
            }
          ]
        },
        "isSystemEntity": false,
        "policies": [],
        "permissions": [
          "ShowIndex"
        ],
        "tags": [],
        "sourceType": "Elastic"
      }
    ],
    "pagesAmount": 1,
    "totalCount": 2
  },
  "sourceTypes": [
    "Kafka",
    "Elastic"
  ]
}

post

Deletes multiple datasets at once

Body

itemsobject[]Optional

Responses

application/json

objectOptional

application/json

post

POST /api/v1/environments/{name}/proxy/api/v1/bulk/datasets/delete HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "items": [
    {
      "id": "kafka://telecom_italia"
    },
    {
      "id": "kafka://bank"
    }
  ]
}

{
  "items": [
    {
      "id": "telecom_italia",
      "success": true
    },
    {
      "id": "bank",
      "success": false,
      "message": "Dataset not found"
    }
  ]
}

post

Body

topicNamestringRequired

replicationintegerOptional

partitionsintegerOptional

configsobjectRequired

Responses

application/json

stringOptional

application/json

post

POST /api/v1/environments/{name}/proxy/api/topics HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 96

{
  "topicName": "text",
  "replication": 1,
  "partitions": 1,
  "configs": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

text

put

Path parameters

topicstringRequired

The topic name

Body

configsobject[]Optional

Responses

application/json

stringOptional

text/plain

put

PUT /api/v1/environments/{name}/proxy/api/configs/topics/{topic} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "configs": [
    {
      "key": "text",
      "value": "text"
    }
  ]
}

text

put

Path parameters

topicNamestringRequired

Body

partitionsintegerRequired

Responses

application/json

objectOptional

application/json

put

PUT /api/v1/environments/{name}/proxy/api/v1/kafka/topics/{topicName}/partitions HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "partitions": 1
}

{
  "partitions": 1
}

post

For AVRO, JSON, CSV, and XML it is required to provide a schema, but not for primitives (INT, LONG, STRING, BYTES), custom Lenses serde or formats like SW*** and TW***. When using AVRO the schema will be registered with the Schema Registry and the process will fail if that step fails.

Body

namestringRequired

replicationintegerOptional

partitionsintegerOptional

configsobjectRequired

formatobjectRequired

Responses

application/json

post

POST /api/v1/environments/{name}/proxy/api/v1/kafka/topic HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "name": "text",
  "replication": 1,
  "partitions": 1,
  "configs": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "format": {
    "key": {
      "format": "TWAVRO",
      "schema": "text"
    },
    "value": {
      "format": "TWAVRO",
      "schema": "text"
    }
  }
}

No content

post

Body

topicNamestringRequired

keyTypestringRequired

valueTypestringRequired

keySchemastringOptional

keySchemaVersionintegerOptional

keySchemaInlinedstringOptional

valueSchemastringOptional

valueSchemaVersionintegerOptional

valueSchemaInlinedstringOptional

descriptionstringOptional

tagsstring[]Optional

additionalInfoanyOptional

Responses

application/json

post

POST /api/v1/environments/{name}/proxy/api/v1/metadata/topics HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 253

{
  "topicName": "text",
  "keyType": "text",
  "valueType": "text",
  "keySchema": "text",
  "keySchemaVersion": 1,
  "keySchemaInlined": "text",
  "valueSchema": "text",
  "valueSchemaVersion": 1,
  "valueSchemaInlined": "text",
  "description": "text",
  "tags": [
    "text"
  ],
  "additionalInfo": null
}

No content

put

Sets a dataset description. Will respond with a bad request if a blank description is supplied

Path parameters

connectionstringRequiredExample: kafka

datasetNamestringRequiredExample: user_details

Body

descriptionstringOptional

Responses

application/json

put

PUT /api/v1/environments/{name}/proxy/api/v1/datasets/{connection}/{datasetName}/description HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "description": "Details about user's purchase history"
}

No content

put

Add one or more tags to a dataset

Path parameters

connectionstringRequiredExample: kafka

datasetNamestringRequiredExample: user_details

Body

tagsobject[]Optional

Responses

application/json

put

PUT /api/v1/environments/{name}/proxy/api/v1/datasets/{connection}/{datasetName}/tags HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "tags": [
    {
      "name": "crm"
    },
    {
      "name": "PII"
    },
    {
      "name": "legacy"
    }
  ]
}

No content