Journeys AI NLQ APIs

This article covers how to get started with the Journeys AI NLQ APIs.

Notes:
The API Tester in the v4 Portal enables you to securely call the methods of these APIs using your organization's Kentik data.
To see examples of the NLQ capabilities currently implemented in the Kentik portal, see Journeys and Query Assistant.
Protobuf and OpenAPI specifications for Kentik’s v6 APIs are available in our api-schema-public repository.

Journeys Usage

The topics below provide important background information for the use of these APIs.

Overview

The Journeys AI NLQ API enables programmatic access to Natural Language Query (NLQ) capabilities that allow the use of natural language to answer questions about your network. The initial method in this API takes a natural language prompt as input and does one of the following:

Returns an answer derived from your organization's DDoS alerts or from the contents of this KB; or
Translates the prompt into a query object that can be used by Kentik's Query API to return results from Data Explorer or Metrics Explorer.

Using an NLQ Result

A query object returned from this API includes a JSON key named "results" that contains a string. After escaping is removed from double-quotes, the prepared string can be passed into a POST call at one of the following Query API endpoints:

Query Data Method: Returns top-X results in a JSON results array. Endpoint: https://api.kentik.com/api/next/v5/query/topxdata
Query Chart Method: Returns image data for a graph similar to a Data Explorer Chart; requires adding an element specifying the desired image file type (for example "imageType":"png") at the end of the query object. Endpoint: https://api.kentik.com/api/next/v5/query/topxchart
Query URL Method: Returns a URL that will open Data Explorer in the Kentik portal with the sidebar set to the query parameters defined in the fields of the request JSON and the query result visualized (graphed) in the display area. Endpoint: https://api.kentik.com/api/next/v5/query/url

Journeys RPCs

The tables below provide a quick reference to key information about each Remote Procedure Call in these APIs. Use the links in the tables to see schemas for the request and/or response body (if any).

Note: To test methods using your own Kentik data, use the portal's API Tester.

GetJourneysNlq

API: JourneysDataService

REST Method

REST Endpoint

Description

GET

/journeys/v202406
/GetJourneysNlq

Perform Natural Language (NLQ) to query object translation

Request body:

None

Response body:

v202406GetJourneysNlqResponse

Parameters:

Name	Description	Required	Type
prompt	The text prompt to be converted to a Journeys NLQ result.	true	string

Journeys Schemas

This API uses the following schemas.

protobufAny

Schema: protobufAny

Type: object

Properties:

Name

Value

typeUrl

type: string

value

type: string

format: byte

rpcStatus

Schema: rpcStatus

Type: object

Properties:

Name

Value

code

type: integer

format: int32

message

type: string

details

type: array

items: $ref: protobufAny

GetJourneysNlqResponse

Schema: v202406GetJourneysNlqResponse

Type: object

Properties:

Name	Value
result	type: string
resultType	$ref: v202406ResultType
resultFormat	$ref: v202406ResultFormat

ResultFormat

Schema: v202406ResultFormat

Type: string

Attributes:

Key	Value
enum	RESULT_FORMAT_UNSPECIFIED, RESULT_FORMAT_JSON, RESULT_FORMAT_MARKDOWN, RESULT_FORMAT_PLAIN_TEXT
default	RESULT_FORMAT_UNSPECIFIED

ResultType

Schema: v202406ResultType

Type: string

Attributes:

Key	Value
enum	RESULT_TYPE_UNSPECIFIED, RESULT_TYPE_ERROR, RESULT_TYPE_DE_QUERY_OBJECT, RESULT_TYPE_ME_QUERY_OBJECT, RESULT_TYPE_KNOWLEDGE_BASE, RESULT_TYPE_DDOS_ALERTS
default	RESULT_TYPE_UNSPECIFIED