Appearance
nova
25 endpoints.
GET /api/v1/nova/settings
Get Settings
200 — Successful Response
json
{
"properties": {
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
},
"kill_switch": {
"type": "boolean",
"title": "Kill Switch",
"default": false
},
"llm_provider": {
"type": "string",
"title": "Llm Provider",
"default": "claude_cli"
},
"openrouter_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Openrouter Api Key"
},
"deepseek_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Deepseek Api Key"
},
"kimi_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Kimi Api Key"
},
"mimo_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mimo Api Key"
},
"openai_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Openai Api Key"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model",
"default": "gpt-6-luna"
},
"background_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Background Model",
"default": "gpt-6-luna"
},
"enable_write_tools": {
"type": "boolean",
"title": "Enable Write Tools",
"default": true
},
"approver_role": {
"type": "string",
"title": "Approver Role",
"default": "admin"
},
"approval_timeout": {
"type": "integer",
"title": "Approval Timeout",
"default": 7200
},
"extra_system_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Extra System Prompt"
}
},
"type": "object",
"title": "AiAgentSettingsOut"
}PUT /api/v1/nova/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"
},
"llm_provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Llm Provider"
},
"openrouter_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Openrouter Api Key"
},
"deepseek_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Deepseek Api Key"
},
"kimi_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Kimi Api Key"
},
"mimo_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mimo Api Key"
},
"openai_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Openai Api Key"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"background_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Background 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
},
"llm_provider": {
"type": "string",
"title": "Llm Provider",
"default": "claude_cli"
},
"openrouter_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Openrouter Api Key"
},
"deepseek_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Deepseek Api Key"
},
"kimi_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Kimi Api Key"
},
"mimo_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mimo Api Key"
},
"openai_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Openai Api Key"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model",
"default": "gpt-6-luna"
},
"background_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Background Model",
"default": "gpt-6-luna"
},
"enable_write_tools": {
"type": "boolean",
"title": "Enable Write Tools",
"default": true
},
"approver_role": {
"type": "string",
"title": "Approver Role",
"default": "admin"
},
"approval_timeout": {
"type": "integer",
"title": "Approval Timeout",
"default": 7200
},
"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/nova/settings/status
Agent Status
Which model runs where, and whether Claude is suspended - and until when.
Owner, 2026-10-27: "show here that Claude is suspended and the date and time it will reactivate. show what Claude Haiku 4.5 will be used for and any other specific models selected. show primary and failover clearly."
The suspension is the CLI's own refusal, kept on the hub by app/services/nova_fallback.py (_remember_suspension): its banner says when the weekly allowance returns ("resets Oct 30, 8am (Africa/Johannesburg)"), so the page can give the exact reactivation, not just "a call failed".
200 — Successful Response
json
{
"additionalProperties": true,
"type": "object",
"title": "Response Agent Status Api V1 Nova Settings Status Get"
}GET /api/v1/nova/settings/openrouter/models
Openrouter Models
Every model OpenRouter serves — the picker behind Nova settings' Model field when the provider is OpenRouter (owner, 2026-10-18: "list all openrouter models"). Cached upstream (see openrouter_models.list_models); ?refresh=1 forces a fresh fetch for a "Reload models" button.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
refresh | query | no | boolean |
200 — Successful Response
json
{
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name",
"default": ""
},
"context_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Context Length"
},
"prompt_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt Price"
},
"completion_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completion Price"
}
},
"type": "object",
"required": [
"id"
],
"title": "OpenRouterModelOut",
"description": "One OpenRouter catalogue entry for the settings dropdown (owner,\n2026-10-18: \"list all openrouter models\")."
},
"title": "Response Openrouter Models Api V1 Nova Settings Openrouter Models 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"
}GET /api/v1/nova/settings/deepseek/models
Deepseek Models
DeepSeek's models — the picker behind Nova settings' Model field when the provider is DeepSeek (owner, 2026-10-18: "add deepseeks api"). DeepSeek models are served through OpenRouter's OpenAI-compatible endpoint (see deepseek_models.list_models), so the list is OpenRouter's deepseek/* catalogue.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
refresh | query | no | boolean |
200 — Successful Response
json
{
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name",
"default": ""
},
"context_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Context Length"
},
"prompt_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt Price"
},
"completion_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completion Price"
}
},
"type": "object",
"required": [
"id"
],
"title": "DeepSeekModelOut",
"description": "One DeepSeek model for the settings dropdown (owner, 2026-10-18:\n\"add deepseeks api\"). Same shape as OpenRouterModelOut so the frontend's\nprovider picker is shared."
},
"title": "Response Deepseek Models Api V1 Nova Settings Deepseek Models 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"
}GET /api/v1/nova/settings/mimo/models
Mimo Models
Xiaomi MiMo's chat models — the picker behind Nova settings' Model field when the provider is MiMo (owner, 2026-10-19: "apply new endpoint and api key to nova"). A static list (see mimo_models.list_models): the gateway's /v1/models also serves ASR/TTS voice models that Nova cannot use.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
refresh | query | no | boolean |
200 — Successful Response
json
{
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name",
"default": ""
},
"context_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Context Length"
},
"prompt_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt Price"
},
"completion_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completion Price"
}
},
"type": "object",
"required": [
"id"
],
"title": "DeepSeekModelOut",
"description": "One DeepSeek model for the settings dropdown (owner, 2026-10-18:\n\"add deepseeks api\"). Same shape as OpenRouterModelOut so the frontend's\nprovider picker is shared."
},
"title": "Response Mimo Models Api V1 Nova Settings Mimo Models 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"
}GET /api/v1/nova/settings/openai/models
Openai Models
OpenAI's chat/reasoning models — the picker behind Nova settings' Model field when the provider is ChatGPT (owner, 2026-10-21: "add to nova chatgpt"). A live read of GET /v1/models (see openai_models.list_models), filtered to what a tool loop can run on.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
refresh | query | no | boolean |
200 — Successful Response
json
{
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name",
"default": ""
},
"context_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Context Length"
},
"prompt_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt Price"
},
"completion_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completion Price"
}
},
"type": "object",
"required": [
"id"
],
"title": "DeepSeekModelOut",
"description": "One DeepSeek model for the settings dropdown (owner, 2026-10-18:\n\"add deepseeks api\"). Same shape as OpenRouterModelOut so the frontend's\nprovider picker is shared."
},
"title": "Response Openai Models Api V1 Nova Settings Openai Models 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"
}GET /api/v1/nova/voice
Get Voice
200 — Successful Response
json
{}PUT /api/v1/nova/voice
Update Voice
Request body
json
{
"additionalProperties": true,
"type": "object",
"title": "Body"
}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"
}GET /api/v1/nova/skills
List Skills
The skill catalogue active on THIS site — the curated playbooks Nova loads on demand (nova_skills, see app/seeds/nova_skills_seed.py).
The listing shape only (slug/title/category/app_slug/summary), never the procedures: this exists so the Prompt Academy can show a human what Nova has been taught here, and the full text belongs on the nova-skills grid, which is admin-only and editable.
Site-scoped rather than tenant-scoped, matching the table — a skill is platform know-how, not one org's data. App-gated packs are filtered out on a site without that app, exactly as they are for Nova itself, so this page never advertises a skill the chat does not actually have.
Open to any authenticated user rather than admin-only: hiding the explanation of what Nova can do from the people who will be asking it questions helps nobody, and it exposes no business data.
200 — Successful Response
json
{}GET /api/v1/nova/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 Nova 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/nova/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/nova/conversations/sessions
List Sessions
200 — Successful Response
json
{
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"label": {
"type": "string",
"title": "Label"
},
"summary": {
"type": "string",
"title": "Summary",
"default": ""
},
"last_message_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Message At"
},
"running": {
"type": "boolean",
"title": "Running",
"default": false
},
"asks": {
"type": "boolean",
"title": "Asks",
"default": false
},
"last_message_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Message Id"
},
"waiting_approval": {
"type": "boolean",
"title": "Waiting Approval",
"default": false
},
"user_name": {
"type": "string",
"title": "User Name",
"default": ""
}
},
"type": "object",
"required": [
"id",
"label"
],
"title": "NovaSessionOut",
"description": "One row of the Ask Nova dialog's session picker."
},
"type": "array",
"title": "Response List Sessions Api V1 Nova Conversations Sessions Get"
}GET /api/v1/nova/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"
},
"running": {
"type": "boolean",
"title": "Running",
"default": false
},
"live_steps": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Live Steps"
},
"live_eta": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Live Eta"
},
"turn_steps": {
"additionalProperties": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"type": "object",
"title": "Turn Steps"
},
"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"
},
"pending_approvals": {
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"tool_name": {
"type": "string",
"title": "Tool Name"
},
"summary": {
"type": "string",
"title": "Summary",
"default": ""
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Expires At"
}
},
"type": "object",
"required": [
"id",
"tool_name",
"created_at"
],
"title": "AiAgentPendingApprovalOut"
},
"type": "array",
"title": "Pending Approvals"
},
"follow_ups": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Follow Ups"
}
},
"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/nova/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/nova/conversations/{conversation_id}/close
Close 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/nova/conversations/{conversation_id}/notes
Add Note
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": "NovaNoteIn"
}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/nova/attachments
Upload Attachment
One file for the composer's paperclip (2026-10-02). Stored on this box and returned as {"id", "name", "size"}; the next turn names it by id — see app/apps/erp/services/ai_agent_attachments.py.
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/nova/conversations/{conversation_id}/turns
Start Turn
Start one chat turn in the background and return at once; poll GET /conversations/{id} for the reply. Same scope/confinement as :func:send_message, and the disabled / out-of-credits refusals are checked here first so they still come back as an immediate 409 / 402.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation_id | path | yes | string |
Request body
json
{
"properties": {
"text": {
"type": "string",
"title": "Text"
},
"page": {
"anyOf": [
{
"properties": {
"path": {
"type": "string",
"maxLength": 500,
"title": "Path",
"default": ""
},
"title": {
"type": "string",
"maxLength": 200,
"title": "Title",
"default": ""
},
"context": {
"type": "string",
"maxLength": 20000,
"title": "Context",
"default": ""
},
"visible": {
"type": "string",
"maxLength": 6000,
"title": "Visible",
"default": ""
}
},
"type": "object",
"title": "PageContextIn",
"description": "The page the chat was sent from — see orchestrator ``_turn_context``."
},
{
"type": "null"
}
]
},
"attachments": {
"items": {
"type": "string"
},
"type": "array",
"title": "Attachments",
"default": []
}
},
"type": "object",
"required": [
"text"
],
"title": "SendMessageIn"
}202 — 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/nova/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.
The site scope is enforced on the CONVERSATION, not on this request's body: which agent — and therefore which tool allowlist — a turn runs against is decided by c.agent_profile_id, so confining the row is what actually keeps a narrowed site off the shared agent's tools.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation_id | path | yes | string |
Request body
json
{
"properties": {
"text": {
"type": "string",
"title": "Text"
},
"page": {
"anyOf": [
{
"properties": {
"path": {
"type": "string",
"maxLength": 500,
"title": "Path",
"default": ""
},
"title": {
"type": "string",
"maxLength": 200,
"title": "Title",
"default": ""
},
"context": {
"type": "string",
"maxLength": 20000,
"title": "Context",
"default": ""
},
"visible": {
"type": "string",
"maxLength": 6000,
"title": "Visible",
"default": ""
}
},
"type": "object",
"title": "PageContextIn",
"description": "The page the chat was sent from — see orchestrator ``_turn_context``."
},
{
"type": "null"
}
]
},
"attachments": {
"items": {
"type": "string"
},
"type": "array",
"title": "Attachments",
"default": []
}
},
"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"
},
"credits": {
"anyOf": [
{
"properties": {
"metered": {
"type": "boolean",
"title": "Metered",
"default": false
},
"spent": {
"type": "integer",
"title": "Spent",
"default": 0
},
"balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Balance"
},
"warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Warning"
}
},
"type": "object",
"title": "AiCreditsOut",
"description": "What this turn cost the org's Labib AI allowance, and whether the\ncustomer should be told something about it (2026-09-02, the four-tier\ncredits ladder). ``metered`` is False for an org with no capacity row —\nsee app.apps.erp.services.ai_agent_credits on why those exist."
},
{
"type": "null"
}
]
}
},
"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"
}POST /api/v1/nova/transcribe
Transcribe Audio
Speech → text for the composer's mic button. Returns {"text": ...}; an empty string when nothing intelligible was said.
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/nova/speak
Speak Reply
Text -> MP3 in Nova's voice, for reading a reply aloud. 204 when there is nothing speakable in it.
Request body
json
{
"properties": {
"text": {
"type": "string",
"title": "Text"
}
},
"type": "object",
"required": [
"text"
],
"title": "Body_speak_reply_api_v1_nova_speak_post"
}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/nova/pbx-tts
Pbx Tts
Text -> audio for a PBX prompt. Body: input (required), voice (Azure name, or a legacy OpenAI name), speed (0.5-2.0), and response_format (wav | mp3).
Request body
json
{
"additionalProperties": true,
"type": "object",
"title": "Body"
}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/nova/pbx-transcribe
Pbx Transcribe
Voicemail -> text. Multipart audio (wav/mp3), optional language (ISO code; Whisper detects it when absent). Returns {"text": ...}.
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"
}GET /api/v1/nova/credits
Get Credits
This org's Nova AI credit balance for the month.
Read-only and cheap — the app polls it to render the usage panel and to grey the composer out before the customer types into a conversation that is going to be refused. An unmetered org returns {"metered": false}; the UI shows no allowance at all for one rather than an empty gauge.
Allowed in BOTH site scopes, unlike Settings and Skills: a Website Builder turn on a portal spends the parent ERP's allowance just like any other, and the routing below was written for exactly that case — so a portal that can spend the balance can also read it.
200 — Successful Response
json
{
"properties": {
"metered": {
"type": "boolean",
"title": "Metered",
"default": false
},
"balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Balance"
},
"monthly_allowance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Monthly Allowance"
},
"sent_this_period": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Sent This Period"
},
"plan_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Plan Code"
},
"period_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Period Start"
}
},
"type": "object",
"title": "AiCreditsSummaryOut",
"description": "The org's standing Labib AI balance, for the app's usage panel."
}