Ace

Providers, usage and the assistant’s own surface.

These paths are global — they are not tied to a plugin instance.

31 endpoints. Every one needs Authorization: Bearer <access token>; see Getting Started.

Permissions

The server authorises every call against the signed-in user's permission keys — the same keys the client is held to. For this module they are the AiProvidersManage, AI Usage View and AI Commercial Manage key families. See the Permission Keys reference.

Ai user instruction set

Method	Path	What it does
`POST`	`ai/ai-user-instruction-set`	Ai user instruction set

`POST` `ai/ai-user-instruction-set`

Ai user instruction set.

Payload

Request body

{
  "instructionText": "string"
}

Availability

Method	Path	What it does
`GET`	`ai/availability`	Ai get availability

Chats

Method	Path	What it does
`GET`	`ai/chats`	Ai chat session get all
`POST`	`ai/chats`	Ai chat session create
`DELETE`	`ai/chats/{aiChatSessionId}`	Ai chat session delete
`PUT`	`ai/chats/{aiChatSessionId}`	Ai chat session rename
`GET`	`ai/chats/{aiChatSessionId}/messages`	Ai chat session get messages
`PUT`	`ai/chats/{aiChatSessionId}/provider`	Ai chat session set provider
`POST`	`ai/chats/stream`	Streams one assistant turn. Emits AiChatStreamItemTypes items; tool requests park the loop awaiting AiChatToolResultPost.
`POST`	`ai/chats/tool-results`	Ai chat tool result post

`POST` `ai/chats`

Ai chat session create.

Parameter	In	Required	Type
`title`	query	no	string

Payload

Response

{
  "aiChatSessionId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "title": "string",
  "createdUtc": "2026-10-02T21:14:05Z",
  "updatedUtc": "2026-10-02T21:14:05Z",
  "lastProvider": "string",
  "lastModel": "string",
  "lastSelectedProvider": "string",
  "lastSelectedModel": "string"
}

`PUT` `ai/chats/{aiChatSessionId}`

Ai chat session rename.

Parameter	In	Required	Type
`aiChatSessionId`	path	yes	uuid
`title`	query	no	string

Payload

`PUT` `ai/chats/{aiChatSessionId}/provider`

Ai chat session set provider.

Parameter	In	Required	Type
`aiChatSessionId`	path	yes	uuid
`provider`	query	no	string
`model`	query	no	string

Payload

`POST` `ai/chats/stream`

Streams one assistant turn. Emits AiChatStreamItemTypes items; tool requests park the loop awaiting AiChatToolResultPost..

Payload

Request body

{
  "aiChatSessionId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userMessage": "string",
  "modelOverride": "string",
  "providerId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "toolManifestJson": "string",
  "toolManifestRevision": 42,
  "clientContextJson": "string",
  "correlationId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "attachments": [
    {
      "kind": "string",
      "mimeType": "string",
      "fileName": "Example",
      "dataBase64": "string"
    }
  ]
}

Response

[
  {
    "type": "string",
    "text": "string",
    "toolUseId": "string",
    "toolName": "Example",
    "argumentsJson": "string",
    "execution": "string",
    "notice": "string",
    "tokensIn": 42,
    "tokensOut": 42,
    "tokensCached": 42,
    "errorMessage": "string",
    "failureCode": 42,
    "messageIds": [
      42
    ]
  }
]

`POST` `ai/chats/tool-results`

Ai chat tool result post.

Payload

Request body

{
  "correlationId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "toolUseId": "string",
  "contentJson": "string",
  "isError": true
}

Feedback

Method	Path	What it does
`PUT`	`ai/feedback`	Ai feedback post

`PUT` `ai/feedback`

Ai feedback post.

Payload

Request body

{
  "aiChatSessionMessageId": 42,
  "isPositive": true,
  "reasonCode": "ABC123",
  "comment": "string"
}

Instructions

Method	Path	What it does
`GET`	`ai/instructions`	Ai instruction get all
`PUT`	`ai/instructions`	Ai instruction save
`DELETE`	`ai/instructions/{aiInstructionId}`	Ai instruction delete

`PUT` `ai/instructions`

Ai instruction save.

Payload

Request body

{
  "aiInstructionId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "scope": "string",
  "resellerId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "instructionText": "string",
  "readOnly": true
}

Providers

Method	Path	What it does
`GET`	`ai/providers`	Ai provider get all
`PUT`	`ai/providers`	Ai provider save all
`DELETE`	`ai/providers/{aiProviderId}`	Ai provider delete
`POST`	`ai/providers/discover-models`	Ai provider discover models
`POST`	`ai/providers/test`	Ai provider test

`PUT` `ai/providers`

Ai provider save all.

Payload

Request body

[
  {
    "aiProviderId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
    "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
    "resellerId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
    "name": "Example",
    "providerType": "string",
    "endpoint": "string",
    "hasApiKey": true,
    "apiKeyMaskedTail": "string",
    "newApiKey": "string",
    "defaultModel": "string",
    "models": [
      {
        "id": "string",
        "enabled": true,
        "capabilities": [],
        "contextWindow": 125.5,
        "warm": true
      }
    ],
    "priority": 42,
    "enabled": true,
    "maxTokens": 42,
    "contextWindowTokens": 125.5,
    "resolvedContextWindow": 125.5,
    "resolvedContextWindowSource": "string",
    "readOnly": true,
    "poolKey": "string",
    "maxConcurrentStreams": 42,
    "keepModelsLoaded": true,
    "hardwareProfileJson": "string",
    "capabilityModels": [
      {
        "capability": "string",
        "modelId": "string"
      }
    ],
    "metered": true,
    "costMultiplier": 125.5,
    "modelCosts": [
      {
        "model": "string",
        "multiplier": 125.5
      }
    ],
    "canEditCommercial": true
  }
]

`POST` `ai/providers/discover-models`

Ai provider discover models.

Payload

Request body

{
  "aiProviderId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "resellerId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "name": "Example",
  "providerType": "string",
  "endpoint": "string",
  "hasApiKey": true,
  "apiKeyMaskedTail": "string",
  "newApiKey": "string",
  "defaultModel": "string",
  "models": [
    {
      "id": "string",
      "enabled": true,
      "capabilities": [
        {}
      ],
      "contextWindow": 125.5,
      "warm": true
    }
  ],
  "priority": 42,
  "enabled": true,
  "maxTokens": 42,
  "contextWindowTokens": 125.5,
  "resolvedContextWindow": 125.5,
  "resolvedContextWindowSource": "string",
  "readOnly": true,
  "poolKey": "string",
  "maxConcurrentStreams": 42,
  "keepModelsLoaded": true,
  "hardwareProfileJson": "string",
  "capabilityModels": [
    {
      "capability": "string",
      "modelId": "string"
    }
  ],
  "metered": true,
  "costMultiplier": 125.5,
  "modelCosts": [
    {
      "model": "string",
      "multiplier": 125.5
    }
  ],
  "canEditCommercial": true
}

Response

{
  "success": true,
  "error": "string",
  "discoveredModels": [
    "string"
  ],
  "discoveredModelItems": [
    {
      "id": "string",
      "enabled": true,
      "capabilities": [
        {}
      ],
      "contextWindow": 125.5,
      "warm": true
    }
  ]
}

`POST` `ai/providers/test`

Ai provider test.

Payload

Request body

{
  "aiProviderId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "resellerId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "name": "Example",
  "providerType": "string",
  "endpoint": "string",
  "hasApiKey": true,
  "apiKeyMaskedTail": "string",
  "newApiKey": "string",
  "defaultModel": "string",
  "models": [
    {
      "id": "string",
      "enabled": true,
      "capabilities": [
        {}
      ],
      "contextWindow": 125.5,
      "warm": true
    }
  ],
  "priority": 42,
  "enabled": true,
  "maxTokens": 42,
  "contextWindowTokens": 125.5,
  "resolvedContextWindow": 125.5,
  "resolvedContextWindowSource": "string",
  "readOnly": true,
  "poolKey": "string",
  "maxConcurrentStreams": 42,
  "keepModelsLoaded": true,
  "hardwareProfileJson": "string",
  "capabilityModels": [
    {
      "capability": "string",
      "modelId": "string"
    }
  ],
  "metered": true,
  "costMultiplier": 125.5,
  "modelCosts": [
    {
      "model": "string",
      "multiplier": 125.5
    }
  ],
  "canEditCommercial": true
}

Response

{
  "success": true,
  "error": "string",
  "discoveredModels": [
    "string"
  ],
  "discoveredModelItems": [
    {
      "id": "string",
      "enabled": true,
      "capabilities": [
        {}
      ],
      "contextWindow": 125.5,
      "warm": true
    }
  ]
}

Scope policies

Method	Path	What it does
`GET`	`ai/scope-policies`	Ai scope policy get all
`PUT`	`ai/scope-policies`	Ai scope policy save
`DELETE`	`ai/scope-policies/{aiScopePolicyId}`	Ai scope policy delete

`PUT` `ai/scope-policies`

Ai scope policy save.

Payload

Request body

{
  "aiScopePolicyId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "resellerId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "disabled": true,
  "dailyTokenLimitPerUser": 42,
  "monthlyTokenLimitPerUser": 42,
  "showWhenUnconfigured": true,
  "weeklyTokenLimitPerUser": 42,
  "dailyUsageUnitPool": 42,
  "weeklyUsageUnitPool": 42,
  "monthlyUsageUnitPool": 42,
  "poolTimeZone": "string",
  "monthlyResetAnchor": 42,
  "monthlyResetDay": 42,
  "weeklyResetDay": 42,
  "warnThresholdPercent": 42,
  "allowDelegatedPools": true,
  "readOnly": true,
  "canEditCommercial": true
}

Server status

Method	Path	What it does
`GET`	`ai/server-status`	Ai server status get

Usage

Method	Path	What it does
`POST`	`ai/usage`	Ai usage get
`POST`	`ai/usage/commercial-changes`	Ai commercial changes get
`GET`	`ai/usage/me`	Ai my usage get
`POST`	`ai/usage/tool-failures`	Ai tool failure samples get

`POST` `ai/usage`

Ai usage get.

Payload

Request body

{
  "fromUtc": "2026-10-02T21:14:05Z",
  "toUtc": "2026-10-02T21:14:05Z",
  "resellerId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "provider": "string",
  "model": "string"
}

Response

{
  "tokensIn": 42,
  "tokensOut": 42,
  "turns": 42,
  "activeUsers": 42,
  "stops": 42,
  "truncations": 42,
  "queueWaits": 42,
  "queueTimeouts": 42,
  "firstTokenMsSum": 42,
  "firstTokenCount": 3,
  "meteredTokens": 42,
  "cachedTokens": 42,
  "usageUnits": 42,
  "allowances": [
    {
      "scope": "string",
      "scopeId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
      "scopeName": "Example",
      "window": "string",
      "used": 42,
      "limit": 42,
      "percent": 42,
      "resetUtc": "2026-10-02T21:14:05Z"
    }
  ],
  "warnThresholdPercent": 42,
  "rows": [
    {
      "bucketUtc": "2026-10-02T21:14:05Z",
      "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
      "userId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
      "provider": "string",
      "model": "string",
      "tokensIn": 42,
      "tokensOut": 42,
      "turns": 42,
      "stops": 42,
      "truncations": 42,
      "firstTokenMsSum": 42,
      "firstTokenCount": 3,
      "turnDurationMsSum": 42,
      "queueWaits": 42,
      "queueWaitMsSum": 42,
      "queueTimeouts": 42,
      "meteredTokens": 42,
      "cachedTokens": 42,
      "usageUnits": 42,
      "costOwnerTier": 42
    }
  ],
  "toolRows": [
    {
      "bucketUtc": "2026-10-02T21:14:05Z",
      "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
      "toolName": "Example",
      "calls": 42,
      "errors": 42,
      "durationMsSum": 42
    }
  ]
}

`POST` `ai/usage/commercial-changes`

Ai commercial changes get.

Payload

Request body

{
  "fromUtc": "2026-10-02T21:14:05Z",
  "toUtc": "2026-10-02T21:14:05Z",
  "resellerId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "userId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "provider": "string",
  "model": "string"
}

Response

[
  {
    "dataOwnerId": 42,
    "dataTimeStamp": "2026-10-02T21:14:05Z",
    "description": "Example description",
    "historyTypeId": 42,
    "referenceId": "string",
    "pluginInstalledId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
    "serviceUser": true,
    "sessionHistoryId": 42,
    "userGroupID": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
    "userID": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
    "userName": "Example",
    "utcOffset": 42
  }
]

`POST` `ai/usage/tool-failures`

Ai tool failure samples get.

Parameter	In	Required	Type
`toolName`	query	no	string

Payload

Response

[
  {
    "id": 1042,
    "timestampUtc": "2026-10-02T21:14:05Z",
    "userGroupId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
    "userId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
    "provider": "string",
    "model": "string",
    "toolName": "Example",
    "argumentsJson": "string",
    "errorText": "string",
    "durationMs": 42,
    "aiChatSessionId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50"
  }
]

User instruction

Method	Path	What it does
`GET`	`ai/user-instruction`	Ai user instruction get

User memories

Method	Path	What it does
`GET`	`ai/user-memories`	Ai user memory get all
`POST`	`ai/user-memories`	Ai user memory save
`DELETE`	`ai/user-memories/{aiUserMemoryId}`	Ai user memory delete

`POST` `ai/user-memories`

Ai user memory save.

Parameter	In	Required	Type
`memoryText`	query	no	string

Payload

Response

{
  "aiUserMemoryId": "3b7f5c2e-9a41-4d8b-bb0e-7c1a2d3e4f50",
  "memoryText": "string",
  "createdUtc": "2026-10-02T21:14:05Z"
}

Ai user instruction set​

POST ai/ai-user-instruction-set​

Availability​

Chats​

POST ai/chats​

PUT ai/chats/{aiChatSessionId}​

PUT ai/chats/{aiChatSessionId}/provider​

POST ai/chats/stream​

POST ai/chats/tool-results​

Feedback​

PUT ai/feedback​

Instructions​

PUT ai/instructions​

Providers​

PUT ai/providers​

POST ai/providers/discover-models​

POST ai/providers/test​

Scope policies​

PUT ai/scope-policies​

Server status​

Usage​

POST ai/usage​

POST ai/usage/commercial-changes​

POST ai/usage/tool-failures​

User instruction​

User memories​

POST ai/user-memories​

Ai user instruction set

`POST` `ai/ai-user-instruction-set`

Availability

Chats

`POST` `ai/chats`

`PUT` `ai/chats/{aiChatSessionId}`

`PUT` `ai/chats/{aiChatSessionId}/provider`

`POST` `ai/chats/stream`

`POST` `ai/chats/tool-results`

Feedback

`PUT` `ai/feedback`

Instructions

`PUT` `ai/instructions`

Providers

`PUT` `ai/providers`

`POST` `ai/providers/discover-models`

`POST` `ai/providers/test`

Scope policies

`PUT` `ai/scope-policies`

Server status

Usage

`POST` `ai/usage`

`POST` `ai/usage/commercial-changes`

`POST` `ai/usage/tool-failures`

User instruction

User memories

`POST` `ai/user-memories`