Lenses API Spec

API reference documentation for Lenses.

PreviousAPI Authentication NextWebsocket Spec

Last updated 2 months ago

Was this helpful?

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

post

/v1/login

Authorizations

Body

usernamestringrequired

passwordstringrequired

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/login' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "text",
    "password": "text"
  }'

204

No body

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

Lists all environments

get

/v1/environments

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/environments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "tier": "development",
      "status": {
        "agent_connected": true,
        "agent": {
          "updated_at": "2025-03-06T23:51:04.264Z",
          "roundtrip_duration": 1,
          "agent": {
            "hostname": "text",
            "version": "text"
          },
          "metrics": {
            "kafka": {
              "version": "text",
              "num_brokers": 1,
              "updated_at": "2025-03-06T23:51:04.264Z"
            },
            "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-06T23:51:04.264Z"
            },
            "apps": {
              "num_consumers": 1,
              "num_other_apps": 1,
              "updated_at": "2025-03-06T23:51:04.264Z"
            },
            "connect": {
              "num_clusters": 1,
              "num_connectors": 1,
              "updated_at": "2025-03-06T23:51:04.264Z"
            },
            "other": {
              "num_issues": 1,
              "updated_at": "2025-03-06T23:51:04.264Z"
            }
          }
        }
      },
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Creates a new environment.

post

/v1/environments

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: 150

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

metadataobject

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

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

Responses

application/json

cURL

JavaScript

Python

HTTP

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"
    }
  }'

201

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-03-06T23:51:04.264Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "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-06T23:51:04.264Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "agent_key": "text"
}

Happy response.

Retrieves a single environment by name.

get

/v1/environments/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-03-06T23:51:04.264Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "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-06T23:51:04.264Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

Updates an environment.

patch

/v1/environments/{name}

Authorizations

Path parameters

namestringrequired

Body

tierstring · enum

Enumerates Tiers.

Options: development, staging, production

metadataobject

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: 150

Updates the display name of the environment.

Responses

application/json

cURL

JavaScript

Python

HTTP

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"
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-03-06T23:51:04.264Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "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-06T23:51:04.264Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-03-06T23:51:04.264Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

Deletes an environment.

delete

/v1/environments/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/environments/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

Successful deletion.

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.

get

/v1/environments/{name}/proxy/

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

default

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

Error object.

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

get

/v1/environments/{name}/proxy/api/v1/datasets/{connection}//{dataset}

Authorizations

Path parameters

namestringrequired

connectionstringrequired

Example: kafka

datasetstringrequired

Example: customer-positions

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/{connection}/{dataset}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

401

402

403

404

500

{
  "name": "text",
  "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",
        "isNullable": true,
        "default": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ]
      }
    ],
    "value": [
      {
        "name": "text",
        "type": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "isNullable": true,
        "default": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ]
      }
    ]
  },
  "isSystemEntity": true,
  "isMarkedForDeletion": true,
  "isCompacted": true,
  "sizeBytes": 1,
  "description": "text",
  "retentionMs": 1,
  "retentionBytes": 1,
  "backupRestoreState": {},
  "sourceType": "text",
  "highlights": [
    {
      "fieldName": "text",
      "startIndex": 1,
      "endIndex": 1,
      "arrayIndex": 1
    }
  ],
  "policies": [
    {
      "policyId": "text",
      "policyName": "text",
      "policyCategory": "text",
      "obfuscation": "text",
      "matchingKeyFields": [
        {
          "name": "text",
          "parents": [
            "text"
          ]
        }
      ],
      "matchingValueFields": [
        {
          "name": "text",
          "parents": [
            "text"
          ]
        }
      ]
    }
  ],
  "permissions": [
    "text"
  ],
  "tags": [
    {
      "name": "text",
      "count": 1
    }
  ]
}

Retrieves a list of datasets

get

/v1/environments/{name}/proxy/api/v1/datasets

Authorizations

Path parameters

namestringrequired

Query parameters

pageinteger

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

querystring

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

Example: name

connectionsstring[]

tagsstring[]

sortBystring · enum

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 · enum

Sorting order. Defaults to ascending

Options: asc, desc

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)

formatstring[]

hasRecordsboolean

Filter based on whether the dataset has records

compactedboolean

Filter based on compacted. Relevant only when sourceType is Kafka

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets?pageSize=1' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

401

402

403

404

500

{
  "datasets": {
    "pagesAmount": 1,
    "totalCount": 1,
    "values": [
      {
        "name": "text",
        "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",
              "isNullable": true,
              "default": "text",
              "ancestors": [
                "text"
              ],
              "highlights": [
                {
                  "fieldName": "text",
                  "startIndex": 1,
                  "endIndex": 1,
                  "arrayIndex": 1
                }
              ]
            }
          ],
          "value": [
            {
              "name": "text",
              "type": "text",
              "typeDetails": {
                "lensesDataType": "text"
              },
              "description": "text",
              "isNullable": true,
              "default": "text",
              "ancestors": [
                "text"
              ],
              "highlights": [
                {
                  "fieldName": "text",
                  "startIndex": 1,
                  "endIndex": 1,
                  "arrayIndex": 1
                }
              ]
            }
          ]
        },
        "isSystemEntity": true,
        "isMarkedForDeletion": true,
        "isCompacted": true,
        "sizeBytes": 1,
        "description": "text",
        "retentionMs": 1,
        "retentionBytes": 1,
        "backupRestoreState": {},
        "sourceType": "text",
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "policies": [
          {
            "policyId": "text",
            "policyName": "text",
            "policyCategory": "text",
            "obfuscation": "text",
            "matchingKeyFields": [
              {
                "name": "text",
                "parents": [
                  "text"
                ]
              }
            ],
            "matchingValueFields": [
              {
                "name": "text",
                "parents": [
                  "text"
                ]
              }
            ]
          }
        ],
        "permissions": [
          "text"
        ],
        "tags": [
          {
            "name": "text",
            "count": 1
          }
        ]
      }
    ]
  },
  "sourceTypes": [
    "Kafka"
  ]
}

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

Retrieves a list of dataset tags

get

/v1/environments/{name}/proxy/api/v1/datasets/tags

Authorizations

Path parameters

namestringrequired

Query parameters

querystring

Get tags sorted by dataset count

Example: user

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/tags' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

401

402

403

404

500

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

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

Lists all groups

get

/v1/groups

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Creates a new Group.

post

/v1/groups

Authorizations

Body

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

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 · min: 1 · max: 150

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

descriptionstring · max: 250

Sets the description of the new group.

metadataobject

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

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

membersstring[]

rolesstring[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "description": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "members": [
      "text"
    ],
    "roles": [
      "text"
    ]
  }'

201

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "description": "text",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Gets a group by its name.

get

/v1/groups/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/groups/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "description": "text",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Returns all users

get

/v1/users

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/users' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "last_seen_at": "2025-03-06T23:51:04.264Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-03-06T23:51:04.264Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ]
    }
  ]
}

Happy response.

Deletes a group.

delete

/v1/groups/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/groups/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

Successful deletion.

Updates a group.

patch

/v1/groups/{name}

Authorizations

Path parameters

namestringrequired

Body

display_namestring · min: 1 · max: 150

Updates the display name of the group.

descriptionstring · max: 250

Updates the Group description, if a value is provided.

metadataobject

Patches metadata. It has the following semantics:

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

rolesstring[]

add_membersstring[]

remove_membersstring[]

set_membersstring[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/groups/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "description": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "roles": [
      "text"
    ],
    "add_members": [
      "text"
    ],
    "remove_members": [
      "text"
    ],
    "set_members": [
      "text"
    ]
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "description": "text",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Creates a new user.

post

/v1/users

Authorizations

Body

namestring · min: 1 · max: 100required

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 · min: 1 · max: 150

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

metadataobject

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

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/users' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'

201

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Returns a specific user

get

/v1/users/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/users/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Updates a user.

patch

/v1/users/{name}

Authorizations

Path parameters

namestringrequired

Body

display_namestring · min: 1 · max: 150

Updates the display name of the user.

metadataobject

Patches metadata. It has the following semantics:

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/users/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Deletes a user.

delete

/v1/users/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/users/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

Successful deletion.

Allows updating fields of the user profile.

patch

/v1/users/{name}/profile

Authorizations

Path parameters

namestringrequired

Body

full_namestring · max: 100

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

email_addressstring · max: 100

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/users/{name}/profile' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "full_name": "text",
    "email_address": "text"
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Returns the currently authenticated user

get

/v1/users/me

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/users/me' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

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

put

/v1/users/{name}/groups

Authorizations

Path parameters

namestringrequired

The name of the user.

Body

add_to_groupsstring[]

remove_from_groupsstring[]

set_groupsstring[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.example.com/api/v1/users/{name}/groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "add_to_groups": [
      "text"
    ],
    "remove_from_groups": [
      "text"
    ],
    "set_groups": [
      "text"
    ]
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

User groups membership updated successfully.

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

post

/v1/login

Authorizations

Body

usernamestringrequired

passwordstringrequired

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/login' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "text",
    "password": "text"
  }'

204

No body

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

Deletes all sessions associated with the current user.

delete

/v1/users/me/sessions

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/users/me/sessions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

Happy response.

Returns all ServiceAccounts.

get

/v1/service-accounts

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/service-accounts' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "id": "text",
      "lrn": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "token_expires_at": "2025-03-06T23:51:04.264Z",
      "token_expired": true,
      "last_seen_at": "2025-03-06T23:51:04.264Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-03-06T23:51:04.264Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ]
    }
  ]
}

Happy response.

Creates a new ServiceAccount.

post

/v1/service-accounts

Authorizations

Body

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

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 · min: 1 · max: 150

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

descriptionstring · max: 250

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.

metadataobject

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

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/service-accounts' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "description": "text",
    "token_expires_at": "2025-03-06T23:51:04.264Z",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'

201

default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "description": "text",
  "token_expires_at": "2025-03-06T23:51:04.264Z",
  "token_expired": true,
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token": "text"
}

Happy response.

Returns a specific ServiceAccount.

get

/v1/service-accounts/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/service-accounts/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "description": "text",
  "token_expires_at": "2025-03-06T23:51:04.264Z",
  "token_expired": true,
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Updates a service account.

patch

/v1/service-accounts/{name}

Authorizations

Path parameters

namestringrequired

Body

display_namestring · min: 1 · max: 150

Updates the display name of the service account.

descriptionstring · max: 250

Updates the description of a service account.

metadataobject

Patches metadata. It has the following semantics:

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/service-accounts/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "description": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "description": "text",
  "token_expires_at": "2025-03-06T23:51:04.264Z",
  "token_expired": true,
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Deletes a ServiceAccount.

delete

/v1/service-accounts/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/service-accounts/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

Successful deletion.

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

post

/v1/service-accounts/{name}/renew-token

Authorizations

Path parameters

namestringrequired

Body

token_expires_atstring · date-time

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/service-accounts/{name}/renew-token' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "token_expires_at": "2025-03-06T23:51:04.264Z"
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "description": "text",
  "token_expires_at": "2025-03-06T23:51:04.264Z",
  "token_expired": true,
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token": "text"
}

Happy response.

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

put

/v1/service-accounts/{name}/groups

Authorizations

Path parameters

namestringrequired

The name of the service account.

Body

add_to_groupsstring[]

remove_from_groupsstring[]

set_groupsstring[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.example.com/api/v1/service-accounts/{name}/groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "add_to_groups": [
      "text"
    ],
    "remove_from_groups": [
      "text"
    ],
    "set_groups": [
      "text"
    ]
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "description": "text",
  "token_expires_at": "2025-03-06T23:51:04.264Z",
  "token_expired": true,
  "last_seen_at": "2025-03-06T23:51:04.264Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Service account groups membership updated successfully.

Returns all roles.

get

/v1/roles

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/roles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-03-06T23:51:04.264Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Creates a new role.

post

/v1/roles

Authorizations

Body

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

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 · min: 1 · max: 150

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

metadataobject

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

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

policyobject[]required

Describes the effect for an action and resource.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/roles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "policy": [
      {
        "action": "kafka:ListTopics",
        "resource": "text",
        "effect": "allow"
      }
    ]
  }'

201

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Happy response.

Returns a specific role.

get

/v1/roles/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Happy response.

Updates a role.

patch

/v1/roles/{name}

Authorizations

Path parameters

namestringrequired

Body

display_namestring · min: 1 · max: 150

Updates the display name of the role.

metadataobject

Patches metadata. It has the following semantics:

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

policyobject[]

Describes the effect for an action and resource.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "policy": [
      {
        "action": "kafka:ListTopics",
        "resource": "text",
        "effect": "allow"
      }
    ]
  }'

200

default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-03-06T23:51:04.264Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Happy response.

Deletes a role.

delete

/v1/roles/{name}

Authorizations

Path parameters

namestringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

Successful deletion.

Returns the backend's meta information.

get

/v1/meta-info

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/meta-info' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "version": "text",
  "build_id": "text",
  "backend_build_id": "text",
  "ui_build_id": "text",
  "goos": "text",
  "goarch": "text",
  "started_at": "2025-03-06T23:51:04.264Z",
  "memstats_alloc": 1,
  "memstats_sys": 1,
  "gc_cpu_fraction": 1,
  "num_goroutine": 1
}

Happy response.

Returns the backend's settings information.

get

/v1/settings

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/settings' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "api": {
    "saml": {
      "user_creation_mode": "manual",
      "users_group_membership_management_mode": "manual"
    }
  }
}

Successfully returns application settings response.

Returns HQ's licence.

get

/v1/licence

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/licence' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "expires_at": "2025-03-06T23:51:04.264Z",
  "tier": "community"
}

Successfully returns licence response.

Returns HQ's licence summary.

get

/v1/licence-summary

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.example.com/api/v1/licence-summary' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "is_community": true
}

Successfully returns licence response.

Authentication

Authentication

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes