Table of Contents

Using the REST API for Branding

Read and update branding and theme settings programmatically through the Management API.

Overview

Branding and theme settings are App Configuration keys exposed by the FoundationaLLM.Configuration resource provider as the appConfigurations resource type. The Themes page in the Management Portal uses the same endpoints. There is no separate branding or theme endpoint in the Management API.

Base URL and Authentication

{ManagementAPIUrl}/instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations
  • Add ?api-version=2024-02-16 to every request.
  • Send a Microsoft Entra ID bearer token for the Management API (for example, scope api://FoundationaLLM-Management/Data.Manage).
  • The caller needs the FoundationaLLM.Configuration/appConfigurations/read permission to read, .../write to update, and .../delete to delete.

The resource name is the full App Configuration key, for example FoundationaLLM:Branding:PrimaryColor. A key filter with * returns all matching keys.

Retrieve Branding Settings

GET /instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/FoundationaLLM:Branding:*?api-version=2024-02-16

Use FoundationaLLM:AgentPortal:Themes:* to retrieve the Agent Portal theme catalog, or a full key to retrieve a single value.

Response

[
  {
    "resource": {
      "type": "appconfiguration-key-value",
      "name": "FoundationaLLM:Branding:PrimaryColor",
      "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/FoundationaLLM:Branding:PrimaryColor",
      "display_name": "FoundationaLLM:Branding:PrimaryColor",
      "key": "FoundationaLLM:Branding:PrimaryColor",
      "value": "#131833",
      "content_type": ""
    },
    "roles": [],
    "actions": []
  }
]

Create or Update a Setting

POST /instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/{key}?api-version=2024-02-16
Content-Type: application/json

Request body

{
  "type": "appconfiguration-key-value",
  "name": "FoundationaLLM:Branding:PrimaryColor",
  "key": "FoundationaLLM:Branding:PrimaryColor",
  "value": "#1a2b3c",
  "content_type": ""
}
  • key is required.
  • content_type must be present. Use an empty string or text/plain for branding values and application/json for Agent Portal theme keys.
  • Theme documents and the manifest are sent as a JSON string in value.

Response

{
  "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/FoundationaLLM:Branding:PrimaryColor",
  "resource_exists": true
}

Delete a Setting

DELETE /instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/{key}?api-version=2024-02-16

The Management Portal uses this call to delete Agent Portal theme keys after removing the theme from the manifest. Always update the manifest first so it never references a missing theme.

Code Examples

PowerShell

$baseUrl = "https://your-management-api"
$instanceId = "your-instance-id"
$token = (az account get-access-token --scope "api://FoundationaLLM-Management/Data.Manage" --query accessToken -o tsv).Trim()
$headers = @{ Authorization = "Bearer $token" }
$root = "$baseUrl/instances/$instanceId/providers/FoundationaLLM.Configuration/appConfigurations"

# Get branding settings
$branding = Invoke-RestMethod -Method Get -Headers $headers `
    -Uri "$root/FoundationaLLM:Branding:*?api-version=2024-02-16"

# Update a setting
$body = @{
    type = "appconfiguration-key-value"
    name = "FoundationaLLM:Branding:CompanyName"
    key = "FoundationaLLM:Branding:CompanyName"
    value = "Contoso"
    content_type = ""
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Headers $headers -ContentType "application/json" -Body $body `
    -Uri "$root/FoundationaLLM:Branding:CompanyName?api-version=2024-02-16"

Python

import requests

base_url = "https://your-management-api"
instance_id = "your-instance-id"
headers = {"Authorization": f"Bearer {access_token}"}
root = f"{base_url}/instances/{instance_id}/providers/FoundationaLLM.Configuration/appConfigurations"
params = {"api-version": "2024-02-16"}

# Get branding settings
branding = requests.get(f"{root}/FoundationaLLM:Branding:*", headers=headers, params=params).json()

# Update a setting
key = "FoundationaLLM:Branding:CompanyName"
requests.post(
    f"{root}/{key}",
    headers=headers,
    params=params,
    json={
        "type": "appconfiguration-key-value",
        "name": key,
        "key": key,
        "value": "Contoso",
        "content_type": "",
    },
)

Error Handling

Status code Description
200 Success
400 Invalid request body (for example, missing key or content_type)
401 Unauthorized
403 Forbidden (missing permission)
404 Key not found (delete)
500 Internal server error