Custom apps

Custom apps are full-screen web applications that integrate seamlessly into Kontent.ai. Use them to embed external tools and data sources directly into your project. Unlike element-level custom elements, custom apps work at the environment level. Check how to create and set up custom apps.

Custom app object

Custom app lets you embed external tools, apps, and data sources directly into your project.

id

string · read-only

The custom app's internal identifier.

name

required · string · 1-200 chars

The custom app's display name.

codename

required · string · 1-60 chars

The custom app's codename.

source_url

required · string · max. 250 chars

The custom app's publicly available URL.

config

string · nullable · max. 100000 chars

The custom app's configuration specified as a custom JSON object.

allowed_roles[]

array · unique items

Specifies the roles that can use this custom app in the UI. If set to an empty array [], any user can use the custom app.If you want to allow a role to manage the custom app's settings, adjust role permissions so they have the Manage custom apps permission.

Show child attributes

JSON

{"id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf","name": "Custom App Name","codename": "custom_app_codename","source_url": "https://customapp.net","config": ""{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}"","allowed_roles": [
        {
            "id": "7740a768-bfa5-4f64-bab4-d77cc0791d4c"
        },
        {
            "id": "7a51d721-7302-4a85-b4ce-a6a3f3cce4a6"
        }
]}

Add a custom app

Creates a new custom app.

POST

https://manage.kontent.ai/v2/projects/{environment_id}/custom-apps

Request

Path parameters

environment_id

required · string

Identifies your environment.

Body schema

Application/json

The custom app to be added.

name

required · string · 1-200 chars

The custom app's display name.

codename

required · string · 1-60 chars

The custom app's codename.

source_url

required · string · max. 250 chars

The custom app's publicly available URL.

config

string · nullable · max. 100000 chars

The custom app's configuration specified as a custom JSON object.

allowed_roles[]

array · unique items

Show child attributes

Request samples

Payload
C#
cURL

{
  "name": "My custom app",
  "codename": "custom_app_codename",
  "source_url": "https://customapp.net",
  "config": "{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}",
  "allowed_roles": [
    {
      "id": "f47e5241-9b34-4586-9ef7-caac6d2f2ebe"
    },
    {
      "codename": "project-manager"
    }
  ]
}

Response

Status (201)

The newly added custom app.

id

string · read-only

The custom app's internal identifier.

name

required · string · 1-200 chars

The custom app's display name.

codename

required · string · 1-60 chars

The custom app's codename.

source_url

required · string · max. 250 chars

The custom app's publicly available URL.

config

string · nullable · max. 100000 chars

The custom app's configuration specified as a custom JSON object.

allowed_roles[]

array · unique items

Show child attributes

Example responses

201

{"id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf","name": "Custom App Name","codename": "custom_app_codename","source_url": "https://customapp.net","config": ""{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}"","allowed_roles": [
        {
            "id": "7740a768-bfa5-4f64-bab4-d77cc0791d4c"
        },
        {
            "id": "7a51d721-7302-4a85-b4ce-a6a3f3cce4a6"
        }
]}

Get custom apps

Retrieves custom apps from an environment.

GET

https://manage.kontent.ai/v2/projects/{environment_id}/custom-apps

Request

Path parameters

environment_id

required · string

Identifies your environment.

Header parameters

x-continuation

string

Determines the page of results to retrieve.To get the next page of results, check the pagination object in the API response and set the x-continuation header parameter to the value of the continuation_token property.

Request samples

C#
cURL

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Management;

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY",
    EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID"
});

var response = await client.ListCustomAppsAsync();

Response

Status (200)

A dynamically paginated list of custom apps.

custom_apps[]

required · array · unique items

List of custom apps.

Show child attributes

pagination

required · object

Information about the next page of results.

Show child attributes

Example responses

200

{
  "custom_apps": [
    {
      "id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf",
      "name": "Custom App Name",
      "codename": "custom_app_codename",
      "source_url": "https://customapp.net",
      "config": "\"{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}\"",
      "allowed_roles": [
        {
          "id": "7740a768-bfa5-4f64-bab4-d77cc0791d4c"
        },
        {
          "id": "7a51d721-7302-4a85-b4ce-a6a3f3cce4a6"
        }
      ]
    }
  ],
  "pagination": {
    "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
    "next_page": null
  }
}

Get a custom app

Retrieve a custom app from an environment.

GET

https://manage.kontent.ai/v2/projects/{environment_id}/custom-apps/{custom_app_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

custom_app_identifier

required · string

Identifies the custom app by its internal ID (e.g., f4b3fc05-e988-4dae-9ac1-a94aba566474) or codename (e.g., codename/custom_app_codename).

Request samples

C#
cURL

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Management;

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY",
    EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID"
});

var identifier = Reference.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474"));
//var identifier = Reference.ByCodename("custom_app_codename");

var response = await client.GetCustomAppAsync(identifier);

Response

Status (200)

A single custom app object

id

string · read-only

The custom app's internal identifier.

name

required · string · 1-200 chars

The custom app's display name.

codename

required · string · 1-60 chars

The custom app's codename.

source_url

required · string · max. 250 chars

The custom app's publicly available URL.

config

string · nullable · max. 100000 chars

The custom app's configuration specified as a custom JSON object.

allowed_roles[]

array · unique items

Show child attributes

Example responses

200
404

{"id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf","name": "Custom App Name","codename": "custom_app_codename","source_url": "https://customapp.net","config": ""{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}"","allowed_roles": [
        {
            "id": "7740a768-bfa5-4f64-bab4-d77cc0791d4c"
        },
        {
            "id": "7a51d721-7302-4a85-b4ce-a6a3f3cce4a6"
        }
]}

Modify a custom app

Modify how an existing custom app is set up.

PATCH

https://manage.kontent.ai/v2/projects/{environment_id}/custom-apps/{custom_app_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

custom_app_identifier

required · string

Identifies the custom app by its internal ID (e.g., f4b3fc05-e988-4dae-9ac1-a94aba566474) or codename (e.g., codename/custom_app_codename).

Body schema

Application/json

The operations to perform on the specified custom app object.

array

Any of:

CustomAppsOperationRemove

CustomAppsOperationAddInto

CustomAppsOperationReplace

CustomAppsOperationRemove

op

required · string

Specifies the operation to perform.

value

required · object

Reference to a specific object in the environment.

Show child attributes

property_name

required · string

Specifies the custom app object property where you want to remove existing objects.

Request samples

Payload
C#
cURL

[
  {
    "op": "addInto",
    "property_name": "allowed_roles",
    "value": [
      {
        "codename": "new_allowed_role_codename_to_add"
      }
    ]
  },
  {
    "op": "remove",
    "property_name": "allowed_roles",
    "value": [
      {
        "codename": "allowed_role_codename_to_remove"
      }
    ]
  },
  {
    "op": "replace",
    "property_name": "name",
    "value": "New Custom App Name"
  },
  {
    "op": "replace",
    "property_name": "codename",
    "value": "new_custom_app_codename"
  },
  {
    "op": "replace",
    "property_name": "source_url",
    "value": "https://newcustomapplication.net"
  },
  {
    "op": "replace",
    "property_name": "config",
    "value": null
  },
  {
    "op": "replace",
    "property_name": "allowed_roles",
    "value": [
      {
        "codename": "allowed_role_codename"
      },
      {
        "id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf"
      }
    ]
  }
]

Response

Status (200)

The custom app was successfully modified.

id

string · read-only

The custom app's internal identifier.

name

required · string · 1-200 chars

The custom app's display name.

codename

required · string · 1-60 chars

The custom app's codename.

source_url

required · string · max. 250 chars

The custom app's publicly available URL.

config

string · nullable · max. 100000 chars

The custom app's configuration specified as a custom JSON object.

allowed_roles[]

array · unique items

Show child attributes

Example responses

200
400
404

{
  "id": "dd1439d5-4ee2-4895-a4e4-5b0d9d8c754e",
  "name": "New Custom App Name",
  "codename": "new_custom_app_codename",
  "source_url": "https://newcustomapplication.net",
  "config": null,
  "allowed_roles": [
    {
      "id": "dadc778e-83e4-4386-a4da-719b9456a099"
    },
    {
      "id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf"
    },
    {
      "id": "a650d86c-3691-4c54-8771-d2f86e244475"
    }
  ]
}

Delete a custom app

Deletes a custom app from an environment.

DELETE

https://manage.kontent.ai/v2/projects/{environment_id}/custom-apps/{custom_app_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

custom_app_identifier

required · string

Identifies the custom app by its internal ID (e.g., f4b3fc05-e988-4dae-9ac1-a94aba566474) or codename (e.g., codename/custom_app_codename).

Request samples

C#
cURL

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Management;

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY",
    EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID"
});

var identifier = Reference.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474"));
//var identifier = Reference.ByCodename("my_custom_app");

var response = await client.DeleteCustomAppAsync(identifier);

Response

Status (204)

The specified custom app was deleted.

Empty response

Example responses

404

{
  "request_id": "00000000-0000-0000-8918-0080000000cd",
  "error_code": 100,
  "message": "The requested custom app 'f4b3fc05-e988-4dae-9ac1-a94aba566474' was not found."
}

Custom app object

Custom app lets you embed external tools, apps, and data sources directly into your project.

id

string · read-only

The custom app's internal identifier.

name

required · string · 1-200 chars

The custom app's display name.

codename

required · string · 1-60 chars

The custom app's codename.

source_url

required · string · max. 250 chars

The custom app's publicly available URL.

config

string · nullable · max. 100000 chars

The custom app's configuration specified as a custom JSON object.

allowed_roles[]

array · unique items

Show child attributes

JSON

{"id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf","name": "Custom App Name","codename": "custom_app_codename","source_url": "https://customapp.net","config": ""{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}"","allowed_roles": [
        {
            "id": "7740a768-bfa5-4f64-bab4-d77cc0791d4c"
        },
        {
            "id": "7a51d721-7302-4a85-b4ce-a6a3f3cce4a6"
        }
]}

{ "name": "My custom app", "codename": "custom_app_codename", "source_url": "https://customapp.net", "config": "{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}", "allowed_roles": [ { "id": "f47e5241-9b34-4586-9ef7-caac6d2f2ebe" }, { "codename": "project-manager" } ] }

{"id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf","name": "Custom App Name","codename": "custom_app_codename","source_url": "https://customapp.net","config": ""{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}"","allowed_roles": [ { "id": "7740a768-bfa5-4f64-bab4-d77cc0791d4c" }, { "id": "7a51d721-7302-4a85-b4ce-a6a3f3cce4a6" } ]}

{ "custom_apps": [ { "id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf", "name": "Custom App Name", "codename": "custom_app_codename", "source_url": "https://customapp.net", "config": "\"{\"theme\":{\"color\":\"#007BFF\",\"logo_url\":\"https://assets.customapp.net/logo.png\"},\"features\":{\"enable_notifications\":true,\"enable_advanced_mode\":false}}\"", "allowed_roles": [ { "id": "7740a768-bfa5-4f64-bab4-d77cc0791d4c" }, { "id": "7a51d721-7302-4a85-b4ce-a6a3f3cce4a6" } ] } ], "pagination": { "continuation_token": "W3sidG9rZW4iOiIrUklEOn...", "next_page": null } }

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Management; var client = new ManagementClient(new ManagementOptions { ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY", EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID" }); var identifier = Reference.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474")); //var identifier = Reference.ByCodename("custom_app_codename"); var response = await client.GetCustomAppAsync(identifier);

[ { "op": "addInto", "property_name": "allowed_roles", "value": [ { "codename": "new_allowed_role_codename_to_add" } ] }, { "op": "remove", "property_name": "allowed_roles", "value": [ { "codename": "allowed_role_codename_to_remove" } ] }, { "op": "replace", "property_name": "name", "value": "New Custom App Name" }, { "op": "replace", "property_name": "codename", "value": "new_custom_app_codename" }, { "op": "replace", "property_name": "source_url", "value": "https://newcustomapplication.net" }, { "op": "replace", "property_name": "config", "value": null }, { "op": "replace", "property_name": "allowed_roles", "value": [ { "codename": "allowed_role_codename" }, { "id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf" } ] } ]

{ "id": "dd1439d5-4ee2-4895-a4e4-5b0d9d8c754e", "name": "New Custom App Name", "codename": "new_custom_app_codename", "source_url": "https://newcustomapplication.net", "config": null, "allowed_roles": [ { "id": "dadc778e-83e4-4386-a4da-719b9456a099" }, { "id": "f8f0b5cb-f5b7-42e8-af85-fbdab3ddfacf" }, { "id": "a650d86c-3691-4c54-8771-d2f86e244475" } ] }

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Management; var client = new ManagementClient(new ManagementOptions { ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY", EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID" }); var identifier = Reference.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474")); //var identifier = Reference.ByCodename("my_custom_app"); var response = await client.DeleteCustomAppAsync(identifier);