--- title: "Custom Applications APIs" slug: "custom-applications-apis" description: "Create, retrieve, update, and delete custom applications in your Kentik environment with our API specifications for traffic classification." tags: ["Custom Applications"] updated: 2026-10-14T19:11:27Z published: 2026-10-14T19:11:27Z canonical: "kb.kentik.com/custom-applications-apis" --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.kentik.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 > [!NOTE] > **Notes**: > > - This API is in alpha (`v202501alpha1`). Endpoints and payloads may change in future versions. > - See [**About Custom Applications**](/v1/docs/custom-applications#about-applications) for background on their purpose and usage. > - See [**Kentik APIs**](/v1/docs/apis-overview) 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**](/v1/docs/custom-applications-apis#list-response). **HTTP Request**: `GET /custom_application/v202501alpha1` #### cURL Example The following is a sample request to the List Custom Applications endpoint. ```bash 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: ```json {  "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] > **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**](/v1/docs/custom-applications-apis#get-response) for payload structure details. **HTTP Request**: `GET /custom_application/v202501alpha1/{customApplicationId}` #### Path Parameters | Parameter | Placement | Type | Required | Description | | --- | --- | --- | --- | --- | | `customApplicationId` | path | string | Yes | Unique identifier of the custom application. | > [!NOTE] > **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. ```bash 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: ```json {  "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**](/v1/docs/custom-applications-apis#custom-application-object) object. Only `name` is required. See [**Create Response**](/v1/docs/custom-applications-apis#create-response) for payload structure details. **HTTP Request**: `POST /custom_application/v202501alpha1` #### Request Body Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | Yes | A unique name for the custom application. | | `description` | string | No | An optional description for the custom application. | | `ipRange` | array (string) | No | List of IP addresses in IP/CIDR format. | | `protocol` | array (integer, uint32) | No | List of protocol numbers. | | `port` | array (int64) | No | List of port numbers. | | `asn` | array (int64) | No | List of ASNs. | > [!TIP] > **Tip**: Fields marked read-only in the [**Custom Application**](/v1/docs/custom-applications-apis#custom-application-object) 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. ```bash 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: ```json {  "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**](/v1/docs/custom-applications-apis#custom-application-object) object with the fields described in [**Create a Custom Application**](/v1/docs/custom-applications-apis#create-a-custom-application). Only `name` is required. See [**Update Response**](/v1/docs/custom-applications-apis#update-response) for payload structure details. **HTTP Request**: `PUT /custom_application/v202501alpha1/{customApplicationId}` #### Path Parameters | Parameter | Placement | Type | Required | Description | | --- | --- | --- | --- | --- | | `customApplicationId` | path | string | Yes | Unique identifier of the custom application. | > [!WARNING] > **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. ```bash 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: ```json {  "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: ```bash 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: ```json {  "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**](/v1/docs/custom-applications-apis#delete-response)). **HTTP Request**: `DELETE /custom_application/v202501alpha1/{customApplicationId}` #### Path Parameters | Parameter | Placement | Type | Required | Description | | --- | --- | --- | --- | --- | | `customApplicationId` | path | string | Yes | Unique identifier of the custom application. | > [!NOTE] > **Note:** Deleting a custom application cannot be undone. #### cURL Example The following is a sample request to the Delete a Custom Application endpoint. ```bash 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: ```json {} ``` ## Standard API Responses & Errors ### List Response When calling the List Custom Applications endpoint, the returned JSON wraps the result set in an `applications` array: ```json {  "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: ```json {  "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: ```json {  "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: ```json {  "application": { /* Custom Application Object */ } } ``` ### Delete Response When calling the Delete a Custom Application endpoint, the returned JSON is an empty object: ```json {} ``` ### Error Response If an API request fails, Kentik returns a standard error object containing an error code and a message. | Field | Type | Description | | --- | --- | --- | | `code` | integer (int32) | The numeric error code. | | `message` | string | A human-readable error description. The message ends with a request identifier (`errxid`). Include it when you report an issue. | | `details` | array (protobufAny) | An array of additional error details, if applicable. | #### HTTP Status Codes | Status | Error Code | Meaning | | --- | --- | --- | | 200 | — | The request succeeded. Also returned with an empty `application` object when you call Get a Custom Application with a numeric ID that doesn't exist or was deleted. | | 400 | 3 | The request is invalid. For example, `name` is missing. | | 400 | — | The request body couldn't be parsed. For example, `port` contains a negative number. The response body is plain text, not a JSON error object. | | 500 | 13 | A custom application with the same `name` already exists (`database error: unique_violation`). | | 500 | 13 | You called Get or Delete with a non-numeric ID, or called Delete with an ID that doesn't exist or was already deleted (`internal error`). | #### Example Error Responses Missing required field (HTTP 400): ```json {  "code": 3,  "message": "Missing required fields on customApplication {...} (errxid db231yztkfgg0d9rp5gg)",  "details": [] } ``` Custom application not found (HTTP 500): ```json {  "code": 13,  "message": "internal error (name:error type:object) (errxid db231yztkfgg0gtbfcs0)",  "details": [] } ``` Request for a deleted custom application (HTTP 200): ```json {  "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. | Field | Type | Description | | --- | --- | --- | | `id` | string | Unique identifier of the custom application. Read-only. | | `name` | string | A unique name for the custom application. Required. | | `description` | string | An optional description for the custom application. | | `ipRange` | array (string) | List of IP addresses in IP/CIDR format. | | `protocol` | array (int64) | List of protocol numbers. | | `port` | array (int64) | List of port numbers. | | `asn` | array (int64) | List of ASNs. | | `createdDate` | string (date-time) | Date-time of custom application creation, in UTC. Read-only. | | `updatedDate` | string (date-time) | Date-time of the most recent custom application edit, in UTC. Read-only. | | `userId` | string | ID of the user associated with this custom application. Read-only. |