# Nova AI - Agents Chat API

Interact with specialized AI personas through the agents chat endpoint. Each persona has unique characteristics, expertise, conversation styles, and can be enhanced with custom training data.

> [!IMPORTANT]
> **Conversation History & Logging**
> To save conversation history and use the `conversation_id` parameter for multi-turn chats, you must enable **Detailed Logging** in your API Key settings. If disabled, chats are stateless and won't be saved.

## Endpoint

**POST** `https://novaaiapi.nabzclan.vip/v1/agents/chat/completions`

## Authentication

Include your API key in the `Authorization` header:

```bash
Authorization: Bearer YOUR_API_KEY
```

## Request Parameters

### Required
- **persona_id** (integer): ID of the AI persona to use (e.g., `1` for Code Assistant).
- **messages** (array): A list of message objects, each containing:
  - `role` (string): "user" or "assistant".
  - `content` (string|array): The text content or array of content parts.

### Optional
- **model** (string): Base model ID. Defaults to persona's setting.
- **temperature** (number): Randomness (0-2). Defaults to persona's setting.
- **stream** (boolean): Server-Sent Events streaming.
- **stream_options** (object): Set `include_usage: true` for token usage in final chunk.
- **conversation_id** (string): Continue specific conversation.
- **tools** (array): List of tools the model may call.
- **tool_choice** (string|object): Controls which tool is called.
- **parallel_tool_calls** (boolean): Whether to disable parallel tool execution.
- **top_k** (integer): Limits vocabulary to top K tokens.
- **min_p** (number): Minimum probability threshold.
- **repetition_penalty** (number): Penalty for repeating tokens.
- **seed** (integer): Random seed for determinism.

### Reasoning Parameters (New Unified Format)
- **reasoning** (object): Unified reasoning configuration:
  - `effort` (string): `xhigh`, `high`, `medium`, `low`, `minimal`
  - `max_tokens` (integer): Maximum tokens for reasoning
  - `exclude` (boolean): If true, reasoning is not returned
  - `enabled` (boolean): Enable reasoning with defaults
- **reasoning_effort** (string): *Deprecated* - Use `reasoning.effort` instead.
- **max_completion_tokens** (integer): Max tokens for reasoning + content.

## Vision / Images

Agents can also process images if their base model supports it.

```json
{
  "persona_id": 1,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this architecture diagram." },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.png"
          }
        }
      ]
    }
  ]
}
```

## Tool Calling

Agents support function calling if the underlying model is capable.

```json
{
  "persona_id": 1,
  "messages": [{"role": "user", "content": "What's the weather in London?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          },
          "required": ["location"]
        }
      }
    }
  ]
}
```

## Reasoning Models

You can control reasoning with the new unified `reasoning` parameter:

```json
{
  "persona_id": 1,
  "reasoning": {
    "effort": "high",
    "max_tokens": 8000
  },
  "messages": [{"role": "user", "content": "Analyze this code deeply..."}]
}
```

Response will include reasoning in multiple formats:
- `reasoning` - Full reasoning text (new format)
- `reasoning_content` - Same as reasoning (legacy)
- `reasoning_details` - Structured array with chunks

## Streaming

When `stream: true` is set, the API streams the response as Server-Sent Events (SSE).

```
data: {"id":"...","choices":[{"delta":{"content":"Hello"}}]}
data: {"id":"...","choices":[{"delta":{"content":" world"}}]}
data: [DONE]
```

## Example Request

```bash
curl -X POST https://novaaiapi.nabzclan.vip/v1/agents/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_id": 1,
    "messages": [
      {"role": "user", "content": "Help me optimize this Python function"}
    ]
  }'
```

## Response Format

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "nova_1_1",
  "context_left": 1998379,
  "context_total": 2000000,
  "persona": {
    "id": 1,
    "name": "Code Assistant",
    "description": "Expert programming assistant..."
  },
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "I'd be happy to help! Please share the function.",
      "tool_calls": null,
      "reasoning": null,
      "reasoning_content": null,
      "reasoning_details": null
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 10,
    "total_tokens": 25
  }
}
```

## Training Data Management

Manage persona knowledge via API:

- **GET** `/api/v1/personas/{id}/training-data` - List training data
- **POST** `/api/v1/personas/{id}/training-data` - Add training data
- **PUT/DELETE** `/api/v1/personas/{id}/training-data/{dataId}` - Update/Remove

For full documentation, visit: https://nova-ai.nabzclan.vip/user/developer/docs/agents-chat