Lenses API Spec

API reference documentation for Lenses.

Authentication

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

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

Body

application/json

username*string

password*string

Response

204

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

Request

JavaScriptCurlPython

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

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:11:55.403Z",
      "tier": "development",
      "status": {
        "agent_connected": false,
        "agent": {
          "updated_at": "2025-01-17T06:11:55.403Z",
          "roundtrip_duration": 0,
          "agent": {
            "hostname": "text",
            "version": "text"
          },
          "metrics": {
            "kafka": {
              "version": "text",
              "num_brokers": 0,
              "updated_at": "2025-01-17T06:11:55.403Z"
            },
            "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:11:55.403Z"
            },
            "apps": {
              "num_consumers": 0,
              "num_other_apps": 0,
              "updated_at": "2025-01-17T06:11:55.403Z"
            },
            "connect": {
              "num_clusters": 0,
              "num_connectors": 0,
              "updated_at": "2025-01-17T06:11:55.403Z"
            },
            "other": {
              "num_issues": 0,
              "updated_at": "2025-01-17T06:11:55.403Z"
            }
          }
        }
      }
    }
  ]
}

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:11:55.403Z",
  "tier": "development",
  "status": {
    "agent_connected": false,
    "agent": {
      "updated_at": "2025-01-17T06:11:55.403Z",
      "roundtrip_duration": 0,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "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:11:55.403Z"
        },
        "apps": {
          "num_consumers": 0,
          "num_other_apps": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "connect": {
          "num_clusters": 0,
          "num_connectors": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "other": {
          "num_issues": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        }
      }
    }
  },
  "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:11:55.403Z",
  "tier": "development",
  "status": {
    "agent_connected": false,
    "agent": {
      "updated_at": "2025-01-17T06:11:55.403Z",
      "roundtrip_duration": 0,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "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:11:55.403Z"
        },
        "apps": {
          "num_consumers": 0,
          "num_other_apps": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "connect": {
          "num_clusters": 0,
          "num_connectors": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "other": {
          "num_issues": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        }
      }
    }
  }
}

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:11:55.403Z",
  "tier": "development",
  "status": {
    "agent_connected": false,
    "agent": {
      "updated_at": "2025-01-17T06:11:55.403Z",
      "roundtrip_duration": 0,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "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:11:55.403Z"
        },
        "apps": {
          "num_consumers": 0,
          "num_other_apps": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "connect": {
          "num_clusters": 0,
          "num_connectors": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        },
        "other": {
          "num_issues": 0,
          "updated_at": "2025-01-17T06:11:55.403Z"
        }
      }
    }
  }
}

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

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

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

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
    }
  ]
}

Lists all groups

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

Response

200default

Happy response.

Body

application/json

items*array of CompactGroup (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/groups', {
    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:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ]
}

Creates a new Group.

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

Body

application/json

name*string (hq-resource-name)

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

display_namestring

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

descriptionstring

Sets the description of the new group.

membersarray of string

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

rolesarray of string

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

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

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

users*array of CompactUser (object)

service_accounts*array of CompactServiceAccount (object)

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/groups', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text"
    }),
});
const data = await response.json();

Response

201default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "policy_length": 0
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": false
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "is_admin": false
    }
  ]
}

Gets a group by its name.

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

Path parameters

name*string

Response

200default

Happy response.

Body

application/json

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

users*array of CompactUser (object)

service_accounts*array of CompactServiceAccount (object)

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/groups/{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:11:55.403Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "policy_length": 0
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": false
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "is_admin": false
    }
  ]
}

Returns all users

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

Response

200default

Happy response.

Body

application/json

items*array of User (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/users', {
    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:11:55.403Z",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-01-17T06:11:55.403Z",
          "description": "text",
          "user_count": 0,
          "sa_count": 0,
          "role_count": 0
        }
      ],
      "last_seen_at": "2025-01-17T06:11:55.403Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": false
    }
  ]
}

Deletes a group.

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

Path parameters

name*string

Response

204default

Successful deletion.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/groups/{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"
}

Updates a group.

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

Path parameters

name*string

Body

application/json

display_namestring

Updates the display name of the group.

descriptionstring

Updates the Group description, if a value is provided.

rolesarray of string

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

add_membersarray of string

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

remove_membersarray of string

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

set_membersarray of string

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

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

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

Response

200default

Happy response.

Body

application/json

name*string

Holds the name of the Group. Must be unique.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

description*string

roles*array of CompactRole (object)

users*array of CompactUser (object)

service_accounts*array of CompactServiceAccount (object)

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/groups/{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:11:55.403Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "policy_length": 0
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": false
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "is_admin": false
    }
  ]
}

Creates a new user.

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

Body

application/json

name*string

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

display_namestring

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

metadataMetadata (object)

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

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

Response

201default

Happy response.

Body

application/json

name*string

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

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

is_admin*boolean

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

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

Response

201default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": false
}

Returns a specific user

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

Path parameters

name*string

Response

200default

Happy response.

Body

application/json

name*string

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

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

is_admin*boolean

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/users/{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:11:55.403Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": false
}

Updates a user.

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

Path parameters

name*string

Body

application/json

display_namestring

Updates the display name of the user.

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

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

Response

200default

Happy response.

Body

application/json

name*string

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

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

is_admin*boolean

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/users/{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:11:55.403Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": false
}

Deletes a user.

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

Path parameters

name*string

Response

204default

Successful deletion.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/users/{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"
}

Allows updating fields of the user profile.

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

Path parameters

name*string

Body

application/json

full_namestring

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

email_addressstring

Contains the users' email address, e.g. [e-mail]. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

Response

200default

Happy response.

Body

application/json

name*string

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

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

is_admin*boolean

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/users/{name}/profile', {
    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:11:55.403Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": false
}

Returns the currently authenticated user

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

Response

200default

Happy response.

Body

application/json

UserOrServiceAccount (object)

Represents either a user or service account.

User (object)ServiceAccount (object)

Request

JavaScriptCurlPython

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

Response

200default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": false
}

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

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

Path parameters

name*string

The name of the user.

Body

application/json

add_to_groupsarray of string

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

remove_from_groupsarray of string

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

set_groupsarray of string

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

Response

200default

User groups membership updated successfully.

Body

application/json

name*string

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

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

groups*array of CompactGroup (object)

last_seen_atstring (date-time)

Updates when this user has interaction with the API.

profile*UserProfile (object)

Models a user's Profile.

is_admin*boolean

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/users/{name}/groups', {
    method: 'PUT',
    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:11:55.403Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": false
}

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

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

Body

application/json

username*string

password*string

Response

204

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

Request

JavaScriptCurlPython

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

Deletes all sessions associated with the current user.

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

Response

204default

Happy response.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/users/me/sessions', {
    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"
}

Returns all ServiceAccounts.

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

Response

200default

Happy response.

Body

application/json

items*array of ServiceAccount (object)

Request

JavaScriptCurlPython

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

Response

200default

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "id": "text",
      "lrn": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-01-17T06:11:55.403Z",
          "description": "text",
          "user_count": 0,
          "sa_count": 0,
          "role_count": 0
        }
      ],
      "token_expires_at": "2025-01-17T06:11:55.403Z",
      "token_expired": false,
      "last_seen_at": "2025-01-17T06:11:55.403Z",
      "is_admin": false
    }
  ]
}

Creates a new ServiceAccount.

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

Body

application/json

name*string (hq-resource-name)

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

display_namestring

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

descriptionstring

Sets the description of the new service account.

token_expires_atstring (date-time)

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

metadataMetadata (object)

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

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

Response

201default

Happy response.

Body

application/json

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

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

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

token*string

Request

JavaScriptCurlPython

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

Response

201default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T06:11:55.403Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "is_admin": false,
  "token": "text"
}

Returns a specific ServiceAccount.

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

Path parameters

name*string

Response

200default

Happy response.

Body

application/json

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

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

Response

200default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T06:11:55.403Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "is_admin": false
}

Updates a service account.

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

Path parameters

name*string

Body

application/json

display_namestring

Updates the display name of the service account.

descriptionstring

Updates the description of a service account.

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

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

Response

200default

Happy response.

Body

application/json

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

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

Response

200default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T06:11:55.403Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "is_admin": false
}

Deletes a ServiceAccount.

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

Path parameters

name*string

Response

204default

Successful deletion.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/service-accounts/{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"
}

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

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

Path parameters

name*string

Body

application/json

token_expires_atstring (date-time)

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

Response

200default

Happy response.

Body

application/json

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

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

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

token*string

Request

JavaScriptCurlPython

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

Response

200default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T06:11:55.403Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "is_admin": false,
  "token": "text"
}

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

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

Path parameters

name*string

The name of the service account.

Body

application/json

add_to_groupsarray of string

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

remove_from_groupsarray of string

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

set_groupsarray of string

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

Response

200default

Service account groups membership updated successfully.

Body

application/json

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

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

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

Request

JavaScriptCurlPython

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

Response

200default

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T06:11:55.403Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T06:11:55.403Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T06:11:55.403Z",
  "is_admin": false
}

Returns all roles.

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

Response

200default

Happy response.

Body

application/json

items*array of CompactRole (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/roles', {
    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:11:55.403Z",
      "policy_length": 0
    }
  ]
}

Creates a new role.

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

Body

application/json

name*string (hq-resource-name)

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

display_namestring

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

policy*array of PermissionStatement (object)

Contains a list of permission statements.

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

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

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/roles', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "policy": [
        {
          "action": "kafka:ListTopics",
          "resource": "text",
          "effect": "allow"
        }
      ]
    }),
});
const data = await response.json();

Response

201default

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-01-17T06:11:55.403Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Returns a specific role.

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

Path parameters

name*string

Response

200default

Happy response.

Body

application/json

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

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/roles/{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:11:55.403Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Updates a role.

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

Path parameters

name*string

Body

application/json

display_namestring

Updates the display name of the role.

policyarray of PermissionStatement (object)

Sets, if specififed, the new permission statements.

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

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

Response

200default

Happy response.

Body

application/json

name*string

Holds the unique name of this role.

display_name*string

lrn*string

Contains the resource identifier for use in access control policies.

id*string

created_at*string (date-time)

policy*array of PermissionStatement (object)

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/roles/{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:11:55.403Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ]
}

Deletes a role.

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

Path parameters

name*string

Response

204default

Successful deletion.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/api/v1/roles/{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"
}

Returns the backend's meta information.

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

Response

200default

Happy response.

Body

application/json

version*string

Is set to the HQ build version.

build_id*string

Is set to the HQ build id.

backend_build_id*string

Is set to the HQ backend build id.

ui_build_id*string

Is set to the HQ UI build id.

goos*string

Equals runtime.GOOS.

goarch*string

Equals runtime.GOARCH.

started_at*string (date-time)

Is set to the instant the backend started.

memstats_alloc*integer (int64)

Equals runtime.Memstats.Alloc.

memstats_sys*integer (int64)

Equals runtime.Memstats.Sys.

gc_cpu_fraction*number

Equals runtime.Memstats.GCCPUFraction.

num_goroutine*integer (int32)

Equals runtime.NumGoroutine().

Request

JavaScriptCurlPython

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

Response

200default

{
  "version": "text",
  "build_id": "text",
  "backend_build_id": "text",
  "ui_build_id": "text",
  "goos": "text",
  "goarch": "text",
  "started_at": "2025-01-17T06:11:55.403Z",
  "memstats_alloc": 0,
  "memstats_sys": 0,
  "gc_cpu_fraction": 0,
  "num_goroutine": 0
}

Returns the backend's settings information.

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

Response

200default

Successfully returns application settings response.

Body

application/json

api*APIConfig (object)

Request

JavaScriptCurlPython

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

Response

200default

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

Returns HQ's licence.

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

Response

200default

Successfully returns licence response.

Body

application/json

expires_atstring (date-time)

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

tier*LicenceTier (enum)

Enumerates licence tiers.

communityenterprise

Request

JavaScriptCurlPython

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

Response

200default

{
  "expires_at": "2025-01-17T06:11:55.403Z",
  "tier": "community"
}

Returns HQ's licence summary.

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

Response

200default

Successfully returns licence response.

Body

application/json

is_community*boolean

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

Request

JavaScriptCurlPython

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

Response

200default

{
  "is_community": false
}