Kentik Custom Dimensions API (v6)
Create custom dimensions and populate them with tagging criteria (populators).
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Custom Dimensions API",
"description": "# Overview\nThe Custom Dimensions API enables programmatic access to information on Custom Dimensions and their Populators.\n",
"version": "v202411alpha1",
"contact": {
"name": "Kentik API Engineering",
"url": "https://github.com/kentik/api-schema-public"
}
},
"tags": [
{
"name": "CustomDimensionService"
}
],
"paths": {
"/custom_dimensions/v202411alpha1": {
"get": {
"summary": "List Custom Dimensions",
"description": "Returns an array of custom dimension objects that each contain information about an individual custom dimension.",
"operationId": "ListCustomDimensions",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1ListCustomDimensionsResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"tags": [
"CustomDimensionService"
]
}
},
"/custom_dimensions/v202411alpha1/{customDimensionId}": {
"get": {
"summary": "Custom Dimension Info",
"description": "Returns a custom dimension object containing information about an individual custom dimension.",
"operationId": "GetCustomDimensionInfo",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1GetCustomDimensionInfoResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "customDimensionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"CustomDimensionService"
]
},
"delete": {
"summary": "Delete Custom Dimension",
"description": "Deletes a custom dimension.",
"operationId": "DeleteCustomDimension",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1DeleteCustomDimensionResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "customDimensionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"CustomDimensionService"
]
},
"put": {
"summary": "Update Custom Dimension",
"description": "Updates and returns a custom dimension object containing information about an individual custom dimension (see About Custom Dimensions). Populators are not sent back in the response body. To get them use 'Custom Dimension info' API instead.",
"operationId": "UpdateCustomDimension",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1UpdateCustomDimensionResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "customDimensionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"$ref": "#/components/requestBodies/v202411alpha1CustomDimension"
},
"tags": [
"CustomDimensionService"
]
}
},
"/custom_dimensions/v202411alpha1/{customDimensionId}/populator": {
"post": {
"summary": "Create Populator",
"description": "Creates and returns a populator object containing information about an individual populator.",
"operationId": "CreatePopulator",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1CreatePopulatorResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "customDimensionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"$ref": "#/components/requestBodies/v202411alpha1Populator"
},
"tags": [
"CustomDimensionService"
]
}
},
"/custom_dimensions/v202411alpha1/{customDimensionId}/populator/{populatorId}": {
"get": {
"summary": "Get Populator",
"description": "Get Populator by Dimension and Populator ID.",
"operationId": "GetPopulator",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1GetPopulatorResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "customDimensionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "populatorId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "fieldLimit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"tags": [
"CustomDimensionService"
]
},
"delete": {
"summary": "Delete Populator",
"description": "Deletes a populator.",
"operationId": "DeletePopulator",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1DeletePopulatorResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "customDimensionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "populatorId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"CustomDimensionService"
]
},
"put": {
"summary": "Update Populator",
"description": "Updates and returns a populator object containing information about an individual populator.",
"operationId": "UpdatePopulator",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1UpdatePopulatorResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "customDimensionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "populatorId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"$ref": "#/components/requestBodies/v202411alpha1Populator"
},
"tags": [
"CustomDimensionService"
]
}
},
"/custom_dimensions/v202411alpha1/{customDimensionId}/populator/{populatorId}/field/{fieldName}": {
"get": {
"summary": "Get Populator Field",
"description": "Get Populator field by Dimension, Populator ID, and field name.",
"operationId": "GetPopulatorField",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1GetPopulatorFieldResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "customDimensionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "populatorId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "fieldName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"tags": [
"CustomDimensionService"
]
}
},
"/v1/customdimension": {
"post": {
"summary": "Create Custom Dimension",
"description": "Creates and returns a custom dimension object containing information about an individual custom dimension",
"operationId": "CreateCustomDimension",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1CreateCustomDimensionResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"$ref": "#/components/requestBodies/v202411alpha1CustomDimension"
},
"tags": [
"CustomDimensionService"
]
}
}
},
"security": [
{
"email": [],
"token": []
}
],
"externalDocs": {
"description": "Knowledge base article outlining the purpose and usage of Custom Dimensions and Populators.",
"url": "https://kb.kentik.com/proto/v4/Cb06.htm"
},
"components": {
"requestBodies": {
"v202411alpha1CustomDimension": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1CustomDimension"
}
}
},
"required": true
},
"v202411alpha1Populator": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202411alpha1Populator"
}
}
},
"required": true
}
},
"securitySchemes": {
"email": {
"type": "apiKey",
"name": "X-CH-Auth-Email",
"in": "header"
},
"token": {
"type": "apiKey",
"name": "X-CH-Auth-API-Token",
"in": "header"
}
},
"schemas": {
"protobufAny": {
"type": "object",
"properties": {
"@type": {
"type": "string"
}
},
"additionalProperties": {}
},
"rpcStatus": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/protobufAny"
}
}
}
},
"v202411alpha1CreateCustomDimensionResponse": {
"type": "object",
"properties": {
"dimension": {
"$ref": "#/components/schemas/v202411alpha1CustomDimension"
}
}
},
"v202411alpha1CreatePopulatorResponse": {
"type": "object",
"properties": {
"populator": {
"$ref": "#/components/schemas/v202411alpha1Populator"
}
}
},
"v202411alpha1CustomDimension": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the custom dimension.",
"readOnly": true
},
"name": {
"type": "string",
"description": "The name of the custom dimension. Must start with 'c_'. Valid characters: alphanumeric dashes and underscores. Length: min=1, max=20."
},
"type": {
"type": "string",
"description": "Type of the custom dimension (valid values: 'string' or 'uint32')",
"title": "should be an enum instead? but also YAGNI"
},
"description": {
"type": "string",
"description": "The name to be displayed of the custom dimension. Valid characters: alphanumeric spaces, dashes and underscores. Length: min=2, max=30."
},
"populators": {
"type": "array",
"items": {
"$ref": "#/components/schemas/v202411alpha1Populator"
},
"description": "Populators associated with this custom dimension.",
"readOnly": true
},
"companyId": {
"type": "string",
"description": "The system-assigned ID of the customer.",
"readOnly": true
},
"createdDate": {
"type": "string",
"format": "date-time",
"description": "Date-time of populator creation, in UTC.",
"readOnly": true
},
"updatedDate": {
"type": "string",
"format": "date-time",
"description": "Date-time of most-recent populator edit, in UTC.",
"readOnly": true
}
},
"required": [
"name",
"type",
"description"
]
},
"v202411alpha1DeleteCustomDimensionResponse": {
"type": "object"
},
"v202411alpha1DeletePopulatorResponse": {
"type": "object"
},
"v202411alpha1ExtendedField": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"v202411alpha1GetCustomDimensionInfoResponse": {
"type": "object",
"properties": {
"dimension": {
"$ref": "#/components/schemas/v202411alpha1CustomDimension"
}
}
},
"v202411alpha1GetPopulatorFieldResponse": {
"type": "object",
"properties": {
"totalCount": {
"type": "integer",
"format": "int64"
},
"offset": {
"type": "integer",
"format": "int64"
},
"limit": {
"type": "integer",
"format": "int64"
},
"extendedFields": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/v202411alpha1ExtendedField"
}
}
}
},
"v202411alpha1GetPopulatorResponse": {
"type": "object",
"properties": {
"populator": {
"$ref": "#/components/schemas/v202411alpha1Populator"
}
}
},
"v202411alpha1ListCustomDimensionsResponse": {
"type": "object",
"properties": {
"dimensions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/v202411alpha1CustomDimension"
}
}
}
},
"v202411alpha1Populator": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the populator.",
"readOnly": true
},
"value": {
"type": "string",
"description": "The value of the dimension. When the custom dimension's type is 'string' - Valid characters: alphanumeric, spaces, dashes and underscores. Length: min=1, max=128. When the custom dimension's type is 'uint32' - Valid values: min=0, max=4294967295."
},
"direction": {
"type": "string",
"description": "The direction of the populator. Valid values: 'src', 'dst', or 'either'."
},
"deviceName": {
"type": "array",
"items": {
"type": "string"
},
"description": "Device names, IPs, or regular expressions. A match results when any specified device name matches the device name or IP address associated with a device sending flow data."
},
"deviceType": {
"type": "array",
"items": {
"type": "string"
},
"description": "Device types or regular expressions. A match results when any specified device type matches the device_type associated with a device sending flow data."
},
"site": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site names or regular expressions. A match results when any specified site matches the site associated with a device sending flow data."
},
"interfaceName": {
"type": "array",
"items": {
"type": "string"
},
"description": "Interface names or regular expressions. A match results when any specified interface name matches the name or description of an interface sending flow data."
},
"addr": {
"type": "array",
"items": {
"type": "string"
},
"description": "IP addresses in IP/CIDR format. A match results when any specified IP address corresponds to a range of IP addresses in incoming flow. It allows IPv6 CIDRs. 'short form' (e.g. 1::2/127) is allowed. If no CIDRs are specified in a tag, the tag will be matched against both incoming IPv4 and v6 flows. If CIDRs are given, the tag will only be matched against the given type of flow; in particular, if you only give IPv4 CIDRs, the tag will not match any IPv6 flows, and vice versa."
},
"port": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "Ports (between 0 and 65535). A match results when any specified port matches a port number in incoming flow."
},
"tcpFlags": {
"type": "integer",
"format": "int64",
"description": "TCP flag: Numbers between 0 and 255 representing an 8-bit binary bit pattern corresponding to TCP flags. A match will result if the value in both the flow bit pattern and the bitmask is 1 at any of the eight places."
},
"protocol": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "Protocol numbers (between 0 and 255). A match results when any specified protocol number is the same as the protocol of the traffic represented by the flow."
},
"asn": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "Last-hop (origin) ASN: ASNs (between 1 and 2^32-1=4294967295). A match results when any specified ASN is the same as the last ASN in the path in the routing table for either the source (SRC IP) or destination (DST IP)."
},
"lasthopAsName": {
"type": "array",
"items": {
"type": "string"
},
"description": "Last-hop (origin) AS Name: AS Names or regular expressions. A match results when any specified AS Name represents the name corresponding to the last ASN in the path in the routing table for either the source (SRC IP) or destination (DST IP)."
},
"nexthopAsn": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kentik/refs/heads/main/openapi/kentik-custom-dimension-openapi.json