AI Requests

Runs a synchronous AI request against a provider and returns the completed result. POST and PUT are equivalent.

POST /api/ai/requests

PUT /api/ai/requests

Send a JSON body. The body object is required. All fields inside the body are optional.

REQUEST Field	Value Type	Description
`providerId`	string	Provider display name or hyphenized name. Empty or omitted uses the default provider.
`userText`	string	User prompt. Defaults to an empty string.
`systemPrompt`	string	Optional system prompt override.
`previousConversation`	array	Prior conversation steps. Defaults to an empty array.
`resourceIds`	array of string	Resource IDs from a previous upload.
`allowedTools`	array of string	If omitted or `null`, all server tools are available. If set, only the listed tools are allowed. Tool names treat spaces and underscores as equivalent.
`forceTool`	boolean	Forces tool execution when supported by the request pipeline.
`maxToolCalls`	number	Maximum tool calls. Negative values are treated as `0`.
`contentSizeExceededStrategy`	string	Enum name for oversized content handling. Unknown values fall back to `SEND_ANYWAY`.
`timeoutMs`	number	Timeout in milliseconds. Default: `120000`.

Conversation step fields in previousConversation and in the response history:

Field	Value Type	Description
`text`	string	Step text.
`stepType`	string	One of `system`, `user`, `assistant`, `tool`.
`toolCalls`	array	Tool calls for assistant steps.
`toolCallId`	string	Tool call ID for tool result steps.

RESPONSE Field	Value Type	Description
`providerId`	string	Provider identifier used for the request.
`providerDisplayName`	string	Provider display name.
`responseText`	string	Assistant response text.
`errorText`	string	Error text, if any.
`lastHttpStatusCode`	number	Last upstream HTTP status code.
`durationMs`	number	Duration in milliseconds.
`history`	array	Conversation history including the new steps.

The call waits until the provider finishes. Unknown providers or communicators return 404. A timeout returns 504. A missing or failed provider response returns 502. Wrong methods return 405.

Example Request

# Request
POST /api/ai/requests HTTP/1.1
Host: helpdesk.example.com
Authorization: Bearer <access_token>
Content-Type: application/json
 
{
  "providerId": "Primary Provider",
  "userText": "Summarize the uploaded notes.",
  "resourceIds": ["res_123"],
  "timeoutMs": 120000
}
 
# Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "providerId": "Primary Provider",
  "providerDisplayName": "Primary Provider",
  "responseText": "The notes describe ...",
  "errorText": "",
  "lastHttpStatusCode": 200,
  "durationMs": 1842,
  "history": [
    {
      "text": "Summarize the uploaded notes.",
      "stepType": "user"
    },
    {
      "text": "The notes describe ...",
      "stepType": "assistant"
    }
  ]
}

AI Requests

POST /api/ai/requests

PUT /api/ai/requests

Example Request

{{welcome.getConfig().welcomeTitle}}

Help