Custom Applications APIs

This article provides programmatic specifications for creating, retrieving, updating, and deleting custom applications in your Kentik environment.

Custom applications let you classify traffic by IP range, protocol, port, and Autonomous System Number (ASN).

• API Version: /custom_application/v202501alpha1

• Protocol: HTTPS

• Format: JSON

Notes:

• This API is in alpha (v202501alpha1). Endpoints and payloads may change in future versions.

• See About Custom Applications for background on their purpose and usage.

• See Kentik APIs for base URLs, authentication specifications, and rate limits.

API Endpoints

List Custom Applications

Returns an array of custom application objects, each containing information about an individual custom application. For details on the returned payload structure, see List Response.

HTTP Request:

GET /custom_application/v202501alpha1

cURL Example

The following is a sample request to the List Custom Applications endpoint.

curl -X GET "https://grpc.api.kentik.com/custom_application/v202501alpha1" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"

Example response:

{
  "applications": [
    {
      "id": "4443",
      "name": "internal-web-app",
      "description": "Internal web application traffic",
      "ipRange": [
        "10.1.0.0/16",
        "10.2.0.0/16"
      ],
      "protocol": [
        6
      ],
      "port": [
        80,
        443
      ],
      "asn": [
        64512
      ],
      "createdDate": "2026-10-05T23:21:28.713Z",
      "updatedDate": "2026-10-05T23:21:28.713Z",
      "userId": "67890"
    }
  ]
}

Note: The above example is abbreviated. The actual response contains every custom application in your account.

Get a Custom Application

Returns a custom application object containing information about an individual custom application. See Get Response for payload structure details.

HTTP Request:

GET /custom_application/v202501alpha1/{customApplicationId}

Path Parameters

Note: If you request an ID that does not exist, the API doesn’t reliably return a 404. Depending on the ID, the API returns either HTTP 500 or HTTP 200 with an empty application object (id and name are empty strings). Check that id is not empty before using the result.

cURL Example

The following is a sample request to the Get a Custom Application endpoint.

curl -X GET "https://grpc.api.kentik.com/custom_application/v202501alpha1/4443" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"

Example response:

{
  "application": {
    "id": "4443",
    "name": "internal-web-app",
    "description": "Internal web application traffic",
    "ipRange": [
      "10.1.0.0/16",
      "10.2.0.0/16"
    ],
    "protocol": [
      6
    ],
    "port": [
      80,
      443
    ],
    "asn": [
      64512
    ],
    "createdDate": "2026-10-05T23:21:28.713Z",
    "updatedDate": "2026-10-05T23:21:28.713Z",
    "userId": "67890"
  }
}

Create a Custom Application

Creates a custom application and returns a custom application object containing information about it. The request body is a Custom Application object. Only name is required. See Create Response for payload structure details.

HTTP Request:

POST /custom_application/v202501alpha1

Request Body Fields

Tip: Fields marked read-only in the Custom Application object (id, createdDate, updatedDate, userId) are assigned by Kentik and do not need to be included in the request.

cURL Example

The following is a sample request to the Create a Custom Application endpoint.

curl -X POST "https://grpc.api.kentik.com/custom_application/v202501alpha1" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "internal-web-app", "description": "Internal web application traffic", "ipRange": ["10.1.0.0/16", "10.2.0.0/16"], "protocol": [6], "port": [80, 443], "asn": [64512]}'

Example response:

{
  "application": {
    "id": "4443",
    "name": "internal-web-app",
    "description": "Internal web application traffic",
    "ipRange": [
      "10.1.0.0/16",
      "10.2.0.0/16"
    ],
    "protocol": [
      6
    ],
    "port": [
      80,
      443
    ],
    "asn": [
      64512
    ],
    "createdDate": "2026-10-05T23:21:28.713Z",
    "updatedDate": "2026-10-05T23:21:28.713Z",
    "userId": "67890"
  }
}

Update a Custom Application

Updates a custom application and returns the updated custom application object. The request body is a Custom Application object with the fields described in Create a Custom Application. Only name is required. See Update Response for payload structure details.

HTTP Request:

PUT /custom_application/v202501alpha1/{customApplicationId}

Path Parameters

Important: Updating a custom application replaces its entire definition. If you omit any of description, ipRange, protocol, port, or asn , the API resets them to empty. Always send the complete set of values you want to keep.

cURL Example

The following is a sample request to the Update a Custom Application endpoint.

curl -X PUT "https://grpc.api.kentik.com/custom_application/v202501alpha1/4443" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "internal-web-app", "description": "Updated description", "ipRange": ["10.1.0.0/16", "10.2.0.0/16"], "protocol": [6], "port": [80, 443], "asn": [64512]}'

Example response:

{
  "application": {
    "id": "4443",
    "name": "internal-web-app",
    "description": "Updated description",
    "ipRange": [
      "10.1.0.0/16",
      "10.2.0.0/16"
    ],
    "protocol": [
      6
    ],
    "port": [
      80,
      443
    ],
    "asn": [
      64512
    ],
    "createdDate": "2026-10-05T23:21:28.713Z",
    "updatedDate": "2026-10-05T23:21:29.971Z",
    "userId": "67890"
  }
}

For example, sending only the name field clears all other values:

curl -X PUT "https://grpc.api.kentik.com/custom_application/v202501alpha1/4443" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "internal-web-app"}'

Example response:

{
  "application": {
    "id": "4443",
    "name": "internal-web-app",
    "description": "",
    "ipRange": [],
    "protocol": [],
    "port": [],
    "asn": [],
    "createdDate": "2026-10-05T23:21:28.713Z",
    "updatedDate": "2026-10-05T23:21:30.422Z",
    "userId": "67890"
  }
}

Delete a Custom Application

Deletes a custom application. On success, the endpoint returns an empty JSON object (see Delete Response).

HTTP Request:

DELETE /custom_application/v202501alpha1/{customApplicationId}

Path Parameters

Note: Deleting a custom application cannot be undone.

cURL Example

The following is a sample request to the Delete a Custom Application endpoint.

curl -X DELETE "https://grpc.api.kentik.com/custom_application/v202501alpha1/4443" \
  -H "X-CH-Auth-Email: your-email@company.com" \
  -H "X-CH-Auth-API-Token: your-api-token"

Example response:

{}

Standard API Responses & Errors

List Response

When calling the List Custom Applications endpoint, the returned JSON wraps the result set in an applications array:

{
  "applications": [
    { /* Custom Application Object 1 */ },
    { /* Custom Application Object 2 */ }
  ]
}

Get Response

When calling the Get a Custom Application endpoint, the returned JSON wraps the single result into an application object:

{
  "application": { /* Custom Application Object */ }
}

Create Response

When calling the Create a Custom Application endpoint, the returned JSON wraps the newly created custom application in an application object:

{
  "application": { /* Custom Application Object */ }
}

Update Response

When calling the Update a Custom Application endpoint, the returned JSON wraps the updated custom application in an application object:

{
  "application": { /* Custom Application Object */ }
}

Delete Response

When calling the Delete a Custom Application endpoint, the returned JSON is an empty object:

{}

Error Response

If an API request fails, Kentik returns a standard error object containing an error code and a message.

HTTP Status Codes

Example Error Responses

Missing required field (HTTP 400):

{
  "code": 3,
  "message": "Missing required fields on customApplication {...} (errxid db231yztkfgg0d9rp5gg)",
  "details": []
}

Custom application not found (HTTP 500):

{
  "code": 13,
  "message": "internal error (name:error type:object) (errxid db231yztkfgg0gtbfcs0)",
  "details": []
}

Request for a deleted custom application (HTTP 200):

{
  "application": {
    "id": "",
    "name": "",
    "description": "",
    "ipRange": [],
    "protocol": [],
    "port": [],
    "asn": [],
    "userId": "67890"
  }
}

Response Fields

Custom Application Object

The Custom Application object defines the attributes of a custom application. The API returns optional fields that have no value as an empty string (description) or an empty array.