Appearance
ai-agent
7 endpoints.
GET /api/v1/ai-agent/settings
Get Settings
200 — Successful Response
json
{
"properties": {
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
},
"kill_switch": {
"type": "boolean",
"title": "Kill Switch",
"default": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"enable_write_tools": {
"type": "boolean",
"title": "Enable Write Tools",
"default": false
},
"approver_role": {
"type": "string",
"title": "Approver Role",
"default": "admin"
},
"approval_timeout": {
"type": "integer",
"title": "Approval Timeout",
"default": 900
},
"extra_system_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Extra System Prompt"
}
},
"type": "object",
"title": "AiAgentSettingsOut"
}PUT /api/v1/ai-agent/settings
Update Settings
Upsert this tenant's singleton settings row (UniqueConstraint(tenant_id) — created on first write, updated in place after).
Request body
json
{
"properties": {
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enabled"
},
"kill_switch": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Kill Switch"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"enable_write_tools": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Write Tools"
},
"approver_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Approver Role"
},
"approval_timeout": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Approval Timeout"
},
"extra_system_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Extra System Prompt"
}
},
"type": "object",
"title": "AiAgentSettingsUpdate"
}200 — Successful Response
json
{
"properties": {
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
},
"kill_switch": {
"type": "boolean",
"title": "Kill Switch",
"default": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"enable_write_tools": {
"type": "boolean",
"title": "Enable Write Tools",
"default": false
},
"approver_role": {
"type": "string",
"title": "Approver Role",
"default": "admin"
},
"approval_timeout": {
"type": "integer",
"title": "Approval Timeout",
"default": 900
},
"extra_system_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Extra System Prompt"
}
},
"type": "object",
"title": "AiAgentSettingsOut"
}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/ai-agent/conversations
List Conversations
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
agent_profile_name | query | no |
200 — Successful Response
json
{
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"status": {
"type": "string",
"title": "Status"
},
"last_message_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Message At"
},
"agent_profile_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent Profile Name"
}
},
"type": "object",
"required": [
"id",
"status"
],
"title": "AiAgentConversationSummary"
},
"title": "Response List Conversations Api V1 Ai Agent Conversations Get"
}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/ai-agent/conversations
Create Conversation
Request body
json
{
"anyOf": [
{
"properties": {
"agent_profile_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent Profile Name"
}
},
"type": "object",
"title": "AiAgentConversationCreate"
},
{
"type": "null"
}
],
"title": "Body"
}201 — Successful Response
json
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"status": {
"type": "string",
"title": "Status"
},
"last_message_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Message At"
},
"agent_profile_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent Profile Name"
}
},
"type": "object",
"required": [
"id",
"status"
],
"title": "AiAgentConversationSummary"
}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/ai-agent/conversations/{conversation_id}
Get Conversation
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation_id | path | yes | string |
200 — Successful Response
json
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"status": {
"type": "string",
"title": "Status"
},
"last_message_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Message At"
},
"agent_profile_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent Profile Name"
},
"session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Session Id"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"messages": {
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"idx": {
"type": "integer",
"title": "Idx"
},
"role": {
"type": "string",
"title": "Role"
},
"text": {
"type": "string",
"title": "Text"
},
"turn_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Turn Id"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"idx",
"role",
"text",
"created_at"
],
"title": "AiAgentMessageOut"
},
"type": "array",
"title": "Messages"
}
},
"type": "object",
"required": [
"id",
"status"
],
"title": "AiAgentConversationOut"
}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}DELETE /api/v1/ai-agent/conversations/{conversation_id}
Delete Conversation
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/ai-agent/conversations/{conversation_id}/messages
Send Message
Send one chat turn. Long-running when a write tool is in flight (the approval gate blocks this request up to approval_timeout seconds) — async, so it costs nothing to other requests, and the AI Agent draws from its own LLMClient concurrency pool (pool="ai_agent") so it can't starve Qualifier's calls.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation_id | path | yes | string |
Request body
json
{
"properties": {
"text": {
"type": "string",
"title": "Text"
}
},
"type": "object",
"required": [
"text"
],
"title": "SendMessageIn"
}200 — Successful Response
json
{
"properties": {
"message": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"idx": {
"type": "integer",
"title": "Idx"
},
"role": {
"type": "string",
"title": "Role"
},
"text": {
"type": "string",
"title": "Text"
},
"turn_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Turn Id"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"idx",
"role",
"text",
"created_at"
],
"title": "AiAgentMessageOut"
},
"action_log": {
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"turn_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Turn Id"
},
"tool_name": {
"type": "string",
"title": "Tool Name"
},
"tool_input": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Tool Input"
},
"tool_output": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Tool Output"
},
"outcome": {
"type": "string",
"title": "Outcome"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"before_snapshot": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Before Snapshot"
},
"after_snapshot": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "After Snapshot"
},
"approval_request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Approval Request Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"tool_name",
"outcome",
"created_at"
],
"title": "AiAgentActionLogOut"
},
"type": "array",
"title": "Action Log"
}
},
"type": "object",
"required": [
"message"
],
"title": "SendMessageOut"
}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}