# API Reference

Complete reference for the AVCodex Chat Completions endpoint.

---

## Endpoint

```
POST https://app.avcodex.com/api/v1/chat/completions
```

## Request

### Headers

| Header              | Required | Description                  |
|---------------------|----------|------------------------------|
| `Authorization`     | Yes      | `Bearer YOUR_API_KEY`.       |
| `Content-Type`      | Yes      | `application/json`.          |
| `X-Chat-Session-ID` | No       | Alternative session ID.      |
| `X-Correlation-ID`  | No       | Request tracking ID.         |

### Body

```typescript
{
  model: string;          // Your agent's appNameId (e.g., "myagent-123")
  messages: Array<{
    role: "user" | "assistant" | "system";
    content: string;
  }>;
  stream?: boolean;       // Default: false
  chatSessionId?: string; // Continue conversation
}
```

### Parameters

- **model:** your AVCodex agent's `appNameId` (format: `agentname-123`).
- **messages:** array of message objects.
- **stream:** enable streaming (optional).
- **chatSessionId:** continue an existing session (optional).

## Response

### Success (200)

```json
{
  "chatSessionId": "550e8400-e29b-41d4-a716-446655440000",
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699451234,
  "model": "myagent-123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Response text"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}
```

### Error format

All errors return a JSON object with an `error` field:

```json
{
  "error": "Error message describing the issue"
}
```

### Status codes

| Code | Description                            |
|------|----------------------------------------|
| 200  | Success.                               |
| 400  | Invalid request parameters.            |
| 401  | Authentication / authorization failure.|
| 404  | Unknown model (agent).                 |
| 500  | Server error.                          |

### Common errors

#### Invalid request (400)
```json
{
  "error": "`model` is required and must be a string"
}
```

```json
{
  "error": "`messages` must be a non-empty array"
}
```

#### Authentication failed (401)
```json
{
  "error": "Missing API key"
}
```

```json
{
  "error": "Invalid API key"
}
```

```json
{
  "error": "This API is only available on a paid plan.  Visit your dashboard to upgrade."
}
```

#### Model not found (404)
```json
{
  "error": "Unknown model \"invalidagent-999\""
}
```

#### Server errors (500)
```json
{
  "error": "Internal Server Error"
}
```

## Sessions

### New session

Omit `chatSessionId` to start fresh.

### Continue session

Include `chatSessionId` from the previous response. Previous messages are loaded automatically.

## Requirements

- Builder plan or higher (free accounts cannot access the API).
- Valid API key from your agent's Share tab.

*AVCodex · Your AV expertise. Amplified by AI.*