Table of Contents

Management API Reference

Complete endpoint reference for the FoundationaLLM Management API.

Base URL

https://{management-api-url}/instances/{instanceId}

Authentication

All endpoints require Entra ID bearer token:

Authorization: Bearer <jwt-token>

Resource Operations

All resource providers follow a consistent pattern:

/instances/{instanceId}/providers/{providerName}/{resourceType}/{resourceName}

GET - List Resources

GET /instances/{instanceId}/providers/{provider}/{resourceType}

Response (200 OK):

[
  {
    "resource": {
      "type": "agent",
      "name": "my-agent",
      "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent",
      "display_name": "My Agent",
      "description": "Agent description"
    },
    "roles": ["Owner"],
    "actions": ["read", "write", "delete"]
  }
]

GET - Get Resource

GET /instances/{instanceId}/providers/{provider}/{resourceType}/{name}

Response (200 OK):

{
  "resource": {
    "type": "agent",
    "name": "my-agent",
    "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent",
    // Full resource definition
  },
  "roles": ["Owner"],
  "actions": ["read", "write", "delete"]
}

POST - Create/Update Resource

POST /instances/{instanceId}/providers/{provider}/{resourceType}/{name}
Content-Type: application/json

{
  // Resource definition
}

Response (200 OK):

{
  "object_id": "/instances/{instanceId}/providers/{provider}/{resourceType}/{name}"
}

DELETE - Delete Resource

DELETE /instances/{instanceId}/providers/{provider}/{resourceType}/{name}

Response (200 OK):

{
  "object_id": "/instances/{instanceId}/providers/{provider}/{resourceType}/{name}",
  "deleted": true
}

POST - Purge Resource

Permanently removes a soft-deleted resource:

POST /instances/{instanceId}/providers/{provider}/{resourceType}/{name}/purge

Agent Resource Provider

Provider: FoundationaLLM.Agent

Agents

List Agents

GET /instances/{instanceId}/providers/FoundationaLLM.Agent/agents

Get Agent

GET /instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}

Create/Update Agent

POST /instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}
Content-Type: application/json

{
  "type": "agent",
  "name": "my-agent",
  "display_name": "My Agent",
  "description": "Agent description",
  "inline_context": false,
  "conversation_history_settings": {
    "enabled": true,
    "max_history": 5
  },
  "gatekeeper_settings": {
    "use_system_setting": false,
    "options": ["ContentSafety"]
  },
  "workflow_object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/workflows/my-workflow",
  "tool_object_ids": []
}

Workflows

List Workflows

GET /instances/{instanceId}/providers/FoundationaLLM.Agent/workflows

Create/Update Workflow

POST /instances/{instanceId}/providers/FoundationaLLM.Agent/workflows/{workflowName}
Content-Type: application/json

{
  "type": "workflow",
  "name": "my-workflow",
  "workflow_type": "OpenAIAssistants",
  "workflow_host": "LangChain",
  "main_ai_model_object_id": "/instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels/gpt-4o",
  "main_prompt_object_id": "/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/system-prompt"
}

Tools

List Tools

GET /instances/{instanceId}/providers/FoundationaLLM.Agent/tools

Create/Update Tool

POST /instances/{instanceId}/providers/FoundationaLLM.Agent/tools/{toolName}
Content-Type: application/json

{
  "type": "tool",
  "name": "knowledge-search",
  "tool_type": "knowledge-search",
  "description": "Search knowledge base"
}

Prompt Resource Provider

Provider: FoundationaLLM.Prompt

List Prompts

GET /instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts

Get Prompt

GET /instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/{promptName}

Create/Update Prompt

POST /instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/{promptName}
Content-Type: application/json

{
  "type": "prompt",
  "name": "system-prompt",
  "display_name": "System Prompt",
  "description": "Main system prompt",
  "category": "AgentWorkflow",
  "prefix": "You are a helpful assistant...",
  "suffix": ""
}

Data Source Resource Provider

Provider: FoundationaLLM.DataSource

List Data Sources

GET /instances/{instanceId}/providers/FoundationaLLM.DataSource/dataSources

Create/Update Data Source

POST /instances/{instanceId}/providers/FoundationaLLM.DataSource/dataSources/{dataSourceName}
Content-Type: application/json

{
  "type": "data-source",
  "name": "azure-storage",
  "display_name": "Azure Storage",
  "data_source_type": "AzureDataLake",
  "configuration": {
    "connection_string_secret_name": "storage-connection",
    "containers": ["documents"]
  }
}

Data Pipeline Resource Provider

Provider: FoundationaLLM.DataPipeline

See Data Pipelines API for complete documentation.

List Pipelines

GET /instances/{instanceId}/providers/FoundationaLLM.DataPipeline/dataPipelines

Execute Pipeline

POST /instances/{instanceId}/providers/FoundationaLLM.DataPipeline/dataPipelines/{pipelineName}/process

List Pipeline Runs

GET /instances/{instanceId}/providers/FoundationaLLM.DataPipeline/dataPipelineRuns

AI Model Resource Provider

Provider: FoundationaLLM.AIModel

List AI Models

GET /instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels

Create/Update AI Model

POST /instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels/{modelName}
Content-Type: application/json

{
  "type": "ai-model",
  "name": "gpt-4o",
  "display_name": "GPT-4o",
  "model_type": "completion",
  "deployment_name": "gpt-4o-deployment",
  "api_endpoint_object_id": "/instances/{instanceId}/providers/FoundationaLLM.Configuration/apiEndpointConfigurations/azure-openai"
}

Configuration Resource Provider

Provider: FoundationaLLM.Configuration

App Configurations

List Configurations

GET /instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations

Update Configuration

POST /instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/{configName}
Content-Type: application/json

{
  "type": "app-configuration",
  "name": "Branding-CompanyName",
  "key": "FoundationaLLM:Branding:CompanyName",
  "value": "Contoso"
}

API Endpoints

List API Endpoints

GET /instances/{instanceId}/providers/FoundationaLLM.Configuration/apiEndpointConfigurations

Authorization Resource Provider

Provider: FoundationaLLM.Authorization

Role Assignments

List Role Assignments

GET /instances/{instanceId}/providers/FoundationaLLM.Authorization/roleAssignments

Create Role Assignment

POST /instances/{instanceId}/providers/FoundationaLLM.Authorization/roleAssignments/{assignmentName}
Content-Type: application/json

{
  "type": "role-assignment",
  "name": "assignment-guid",
  "principal_id": "user-or-group-guid",
  "principal_type": "User",
  "role_definition_id": "/providers/FoundationaLLM.Authorization/roleDefinitions/1301f8d4-3bea-4880-945f-315dbd2ddb46",
  "scope": "/instances/{instanceId}"
}

Role Definitions

List Role Definitions

GET /instances/{instanceId}/providers/FoundationaLLM.Authorization/roleDefinitions

Status Endpoints

Service Status

GET /status

Response:

{
  "status": "ready",
  "name": "ManagementAPI",
  "version": "1.0.0",
  "instance_id": "instance-guid"
}

Identity Endpoints

Get Current User

GET /instances/{instanceId}/identity

Search Security Principals

GET /instances/{instanceId}/identity/securityPrincipals?search={searchTerm}

Error Responses

Status Code Description
400 BadRequest Invalid request body
401 Unauthorized Authentication required
403 Forbidden Insufficient permissions
404 NotFound Resource not found
409 Conflict Resource already exists
500 InternalError Server error

Error Response Format:

{
  "error": {
    "code": "ResourceNotFound",
    "message": "The resource 'my-agent' was not found in provider 'FoundationaLLM.Agent'."
  }
}