# Chat Completions API

Send messages and get AI responses for tax research questions.

## Endpoint

```
POST /chat/completions
```

**Base URL:** https://api-bizora.ai

## Authentication

```
Authorization: Bearer sk_live_YOUR_API_KEY
```

## Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | Must be `"bizora-1.0"` |
| `messages` | array | Yes | Array of message objects |
| `stream` | boolean | No | Enable streaming (default: `false`) |
| `askMode` | string | No | Canonical mode selector such as `tax_research_fast_research`, `tax_research_deep_research`, or `auto` |
| `allowedAskModes` | array | No | Constrain auto-routing when `askMode` is `auto` |
| `ZeroDataRetention` | boolean | No | Disabled by default. Pass `true` only if you require zero data retention. |

### Parameter Usage by Platform

**Python SDK:**
- Use `extra_body={"askMode": "tax_research_deep_research"}` for deep research

**JavaScript SDK:**
- Use `askMode: "tax_research_deep_research"` directly in the request object

**HTTP/curl:**
- Include `"askMode": "tax_research_deep_research"` in the JSON body

### Supported askMode Values

| Value | Best for |
|---|---|
| `tax_research_normal` | Normal first-party webapp tax research. |
| `tax_research_fast_research` | Fast focused tax research; this is the platform API-key default. |
| `tax_research_deep_research` | Deep multi-step tax research for complex or high-stakes questions. |
| `audit_research` | Comprehensive audit research on complex accounting standards and compliance. |
| `auto` | Backend route selection. Use `allowedAskModes` to constrain routing. |

### Zero Data Retention

Zero data retention is disabled by default. To enable it for a specific request, pass `ZeroDataRetention: true` in the request body.

When enabled, prompt and response content is not retained for that request. Some models or providers may be unavailable because they do not support zero data retention. You should handle abuse monitoring for zero data retention traffic because Bizora has limited content visibility for those requests.

```python
response = client.chat.completions.create(
    model="bizora-1.0",
    messages=[{"role": "human", "content": "What is section 179?"}],
    extra_body={"ZeroDataRetention": True}
)
```

```javascript
const response = await client.chat.completions.create({
  model: 'bizora-1.0',
  messages: [{ role: 'human', content: 'What is section 179?' }],
  ZeroDataRetention: true
});
```

```bash
curl -X POST https://api-bizora.ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{
    "model": "bizora-1.0",
    "messages": [
      {"role": "human", "content": "What is section 179?"}
    ],
    "ZeroDataRetention": true
  }'
```

## Message Format

Each message has a role and content:

```json
{
  "role": "human",
  "content": "What is section 179?"
}
```

**Supported roles:**
- `human` - User messages
- `ai` - AI responses (for conversation history)

### Multi-Turn Conversation Example

```json
{
  "model": "bizora-1.0",
  "messages": [
    {"role": "human", "content": "What is section 179?"},
    {"role": "ai", "content": "Section 179 allows businesses to deduct the full purchase price of qualifying equipment..."},
    {"role": "human", "content": "What are the dollar limits?"}
  ]
}
```

## Basic Examples

### Simple Request

```python
import openai

client = openai.OpenAI(
    api_key="sk_live_YOUR_API_KEY",
    base_url="https://api-bizora.ai"
)

response = client.chat.completions.create(
    model="bizora-1.0",
    messages=[{"role": "human", "content": "What is section 179?"}]
)

print(response.choices[0].message.content)
```

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk_live_YOUR_API_KEY',
  baseURL: 'https://api-bizora.ai'
});

const response = await client.chat.completions.create({
  model: 'bizora-1.0',
  messages: [{ role: 'human', content: 'What is section 179?' }]
});

console.log(response.choices[0].message.content);
```

```bash
curl -X POST https://api-bizora.ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{
    "model": "bizora-1.0",
    "messages": [
      {"role": "human", "content": "What is section 179?"}
    ]
  }'
```

### Streaming Request (Recommended)

```python
# Stream responses in real-time
stream = client.chat.completions.create(
    model="bizora-1.0",
    messages=[{"role": "human", "content": "What is section 179?"}],
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

```javascript
// Stream responses in real-time
const stream = await client.chat.completions.create({
  model: 'bizora-1.0',
  messages: [{ role: 'human', content: 'What is section 179?' }],
  stream: true
});

for await (const chunk of stream) {
  if (chunk.choices[0]?.delta?.content) {
    process.stdout.write(chunk.choices[0].delta.content);
  }
}
```

```bash
# Use -N flag for streaming, -X POST for method
curl -X POST -N https://api-bizora.ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{
    "model": "bizora-1.0",
    "messages": [
      {"role": "human", "content": "What is section 179?"}
    ],
    "stream": true
  }'
```

### Deep Research Mode

```python
# Enable deep research for complex tax analysis
response = client.chat.completions.create(
    model="bizora-1.0",
    messages=[{"role": "human", "content": "Analyze the tax treatment of cryptocurrency staking rewards and airdrops."}],
    extra_body={"askMode": "tax_research_deep_research"}
)

print(response.choices[0].message.content)
```

```javascript
// Enable deep research for complex tax analysis
const response = await client.chat.completions.create({
  model: 'bizora-1.0',
  messages: [{ role: 'human', content: 'Analyze the tax treatment of cryptocurrency staking rewards and airdrops.' }],
  askMode: 'tax_research_deep_research'
});

console.log(response.choices[0].message.content);
```

```bash
curl -X POST https://api-bizora.ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{
    "model": "bizora-1.0",
    "messages": [
      {"role": "human", "content": "Analyze the tax treatment of cryptocurrency staking rewards and airdrops."}
    ],
    "askMode": "tax_research_deep_research"
  }'
```

### Audit Research Mode

```python
# Enable audit research for complex financial analysis
response = client.chat.completions.create(
    model="bizora-1.0",
    messages=[{"role": "human", "content": "Analyze the reporting requirements for lease modifications under ASC 842."}],
    extra_body={"askMode": "audit_research"}
)

print(response.choices[0].message.content)
```

```javascript
// Enable audit research for complex financial analysis
const response = await client.chat.completions.create({
  model: 'bizora-1.0',
  messages: [{ role: 'human', content: 'Analyze the reporting requirements for lease modifications under ASC 842.' }],
  askMode: 'audit_research'
});

console.log(response.choices[0].message.content);
```

```bash
curl -X POST https://api-bizora.ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{
    "model": "bizora-1.0",
    "messages": [
      {"role": "human", "content": "Analyze the reporting requirements for lease modifications under ASC 842."}
    ],
    "askMode": "audit_research"
  }'
```

### Constrained Auto-Routing

Use `askMode: "auto"` with `allowedAskModes` when you want Bizora to dynamically choose between explicitly permitted routes (e.g., fast tax research, deep tax research, and audit research). Note that you will be billed at the rate of whichever specific research mode is ultimately selected.

```python
response = client.chat.completions.create(
    model="bizora-1.0",
    messages=[{"role": "human", "content": "Compare the Jarrett staking case with IRS guidance on crypto rewards."}],
    extra_body={
        "askMode": "auto",
        "allowedAskModes": [
            "tax_research_fast_research",
            "tax_research_deep_research",
        ],
    }
)
```

```javascript
const response = await client.chat.completions.create({
  model: 'bizora-1.0',
  messages: [{ role: 'human', content: 'Compare the Jarrett staking case with IRS guidance on crypto rewards.' }],
  askMode: 'auto',
  allowedAskModes: [
    'tax_research_fast_research',
    'tax_research_deep_research',
  ],
});
```

```bash
curl -X POST https://api-bizora.ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{
    "model": "bizora-1.0",
    "messages": [
      {"role": "human", "content": "Compare the Jarrett staking case with IRS guidance on crypto rewards."}
    ],
    "askMode": "auto",
    "allowedAskModes": [
      "tax_research_fast_research",
      "tax_research_deep_research"
    ]
  }'
```

## Response Format

### Non-Streaming Response

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "bizora-1.0",
  "choices": [{
    "index": 0,
    "message": {
      "role": "ai",
      "content": "Section 179 allows businesses to deduct..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 500,
    "total_tokens": 510
  }
}
```

### Token Usage

The `usage` object reports token usage for the request:

| Field | Description |
|-------|-------------|
| `prompt_tokens` | Tokens from the user-provided input. |
| `completion_tokens` | Tokens in the final answer returned to the user. |
| `total_tokens` | Total tokens across input and output. |

### Streaming Response

Each chunk contains incremental content:

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion.chunk",
  "created": 1677652288,
  "model": "bizora-1.0",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "text chunk"
    },
    "finish_reason": null
  }]
}
```

---

<details>
<summary>Legacy Compatibility & Deprecated Flags</summary>

For older integrations, the following deprecated fields and aliases are still accepted but not recommended for new implementations:

*   **Legacy `askMode` Aliases**:
    *   `normal` (alias for `tax_research_normal`)
    *   `fast_research` (alias for `tax_research_fast_research`)
    *   `web_search` (alias for `tax_research_web_search`)
*   **Legacy Boolean Flags**:
    *   `websearch: true` or `webSearch: true` (maps to `tax_research_web_search`)

Do not combine `askMode` with legacy boolean flags.
</details>

## Next Steps

- [Streaming](./streaming.mdx) - Get real-time responses
- [HTTP Requests](./http-requests.mdx) - Use without SDK
- [Message Types](./message-types.mdx) - Handle custom messages
- [Error Handling](./error-handling.mdx) - Handle errors
- [Rate Limits](./rate-limits.mdx) - Understand limits