Run copilot query
POST/ai/copilot/query
Submits a natural-language query to the AI Copilot and returns the model's response. Queries are evaluated against the tenant's active governance policies before execution; requests that violate a policy will be blocked and logged. Use for ad-hoc AI assistance in any CRM context (e.g. draft an email, summarise a ticket, analyse a deal).
Request
Request body
Content type application/json (required).
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | The natural-language instruction or question for the AI model. Max length: 8000 |
template_id | integer, nullable | No | ID of a saved prompt template to use as the base for this query. |
context | object | No | Structured context data passed to the AI model (e.g. customer_id, module name). |
stream | boolean | No | When true, the response is returned as a server-sent event stream. Default: |
Example
{
"prompt": "Summarise the last 5 support tickets for Acme Corp and identify the most common issue.",
"template_id": 12,
"context": {
"customer_id": 88,
"module": "support"
},
"stream": false
}Responses
200 AI copilot response returned
Content type application/json, object · AiCopilotQueryResponseV1.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Unique query identifier for logging and audit. |
prompt | string | No | The original prompt submitted. |
response | string | No | The AI model's generated response text. |
model | string | No | The AI model identifier used to generate the response. |
policy_result | string | No | Result of the governance policy evaluation for this query. One of: |
tokens_used | integer | No | Total tokens consumed by the prompt and response. |
created_at | string (date-time) | No |
Example
{
"id": "qry_01HXM4K2P3N7V8QRST",
"prompt": "Summarise the last 5 support tickets for Acme Corp and identify the most common issue.",
"response": "Acme Corp's 5 most recent tickets (Apr 2–7) all relate to login failures after the SSO migration. Root cause appears to be an Okta domain mismatch in their identity config.",
"model": "claude-3-haiku-20240307",
"policy_result": "allowed",
"tokens_used": 812,
"created_at": "2026-04-08T10:15:00Z"
}403 Query blocked by an active AI governance policy
422 Validation failed — check prompt length or template_id
Example request
curl -X POST "https://{tenant}.faciotech.net/api/v1/ai/copilot/query" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"prompt": "Summarise the last 5 support tickets for Acme Corp and identify the most common issue.", "template_id": 12, "context": {"customer_id": 88, "module": "support"}, "stream": false}'