Skip to main content

Register an app in DIAL Core

This guide shows you how to register a Custom App in DIAL Core so it becomes discoverable through the Unified API and visible in the DIAL Chat Catalog. You should already have a running Custom App with an accessible HTTP endpoint.

Goal​

Make your Custom App callable through the Unified API at POST /openai/deployments/<APP_NAME>/chat/completions and visible to users in DIAL Chat.

Prerequisites​

  • A running Custom App container with a reachable endpoint (see Getting started with DIAL SDK)
  • Admin access to DIAL Core configuration or the Deployments API

Option 1: Add to config.json​

Add your application to the applications section of DIAL Core's config.json file. This is the simplest approach for fixed deployments.

{
  "applications": {
    "my-app": {
      "endpoint": "http://my-app:5000/openai/deployments/my-app/chat/completions",
      "displayName": "My Application",
      "description": "Brief description of what the app does"
    }
  }
}

The key (my-app) becomes the deployment name used in API calls: POST /openai/deployments/my-app/chat/completions.

Note

Applications registered in config.json are immutable — they cannot be modified through the API or UI. This is suitable for production deployments managed by infrastructure-as-code.

Restart DIAL Core (or wait for config reload) to pick up the change.

Verify: Call the API and confirm a response:

curl http://localhost:8080/openai/deployments/my-app/chat/completions \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -d '{"messages": [{"role": "user", "content": "hello"}]}'

Option 2: Use the Deployments API​

Use the PUT /v1/deployments endpoint to register an application dynamically. Applications created this way can be updated or deleted via the API.

curl -X PUT http://localhost:8080/v1/deployments/my-app \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -d '{
    "my-app": {
      "endpoint": "http://my-app:5000/openai/deployments/my-app/chat/completions",
      "displayName": "My Application",
      "description": "Brief description of what the app does"
    }
  }'

Verify: List deployments and confirm your app appears:

curl http://localhost:8080/openai/deployments \
  -H "api-key: <YOUR_API_KEY>"

Restrict access with roles​

By default, a registered application is available to all authenticated users. To restrict access, add userRoles:

{
  "applications": {
    "my-app": {
      "endpoint": "http://my-app:5000/openai/deployments/my-app/chat/completions",
      "displayName": "My Application",
      "userRoles": ["dev-team"]
    }
  },
  "roles": {
    "dev-team": {
      "limits": {
        "my-app": {}
      }
    }
  }
}

Only users with the dev-team role can access the application. The limits entry under the role grants usage permission — an empty object means no rate limit is imposed.

Configure optional features​

Custom Apps support additional configuration attributes beyond the required endpoint. Add these to your application's JSON object:

AttributePurpose
inputAttachmentTypesMIME types the app accepts (e.g., ["application/pdf", "image/png"])
maxInputAttachmentsMaximum number of files per request
forwardAuthTokenPass the user's auth token to your app (true/false)
features.rateEndpointURL for the rate/feedback endpoint
features.configurationEndpointURL for the configuration UI endpoint
interceptorsList of interceptor deployment names to apply
defaultsDefault parameters passed to the app on every request

Example with attachments and interceptors:

{
  "applications": {
    "doc-qa": {
      "endpoint": "http://doc-qa:5000/openai/deployments/doc-qa/chat/completions",
      "displayName": "Document Q&A",
      "description": "Ask questions about uploaded documents",
      "inputAttachmentTypes": ["application/pdf", "text/plain"],
      "maxInputAttachments": 5,
      "forwardAuthToken": true,
      "interceptors": ["pii-redactor"]
    }
  }
}

For the full attribute reference, see Applications configuration.

Verify in DIAL Chat​

After registration:

  1. Open DIAL Chat in your browser.
  2. Open the Catalog.
  3. Confirm your application appears with the correct name and description.
  4. Start a conversation with the app and send a test message.

Result​

Your Custom App is registered in DIAL Core, callable via the Unified API, and visible in the DIAL Chat Catalog. Users with appropriate roles can discover and interact with it.

Further reading​