Skip to content

nova ​

← All modules

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

NameInRequiredTypeDescription
refreshquerynoboolean

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

NameInRequiredTypeDescription
refreshquerynoboolean

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

NameInRequiredTypeDescription
refreshquerynoboolean

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

NameInRequiredTypeDescription
refreshquerynoboolean

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

NameInRequiredTypeDescription
agent_profile_namequeryno

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

NameInRequiredTypeDescription
conversation_idpathyesstring

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

NameInRequiredTypeDescription
conversation_idpathyesstring

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

NameInRequiredTypeDescription
conversation_idpathyesstring

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

NameInRequiredTypeDescription
conversation_idpathyesstring

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

NameInRequiredTypeDescription
conversation_idpathyesstring

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

NameInRequiredTypeDescription
conversation_idpathyesstring

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

Lubb Business Documentation