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"
    }
  ]
}