# API Reference

Complete reference for the Chat Completions endpoint



## Endpoint

```
POST https://app.chipp.ai/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 app's appNameId (e.g., "myapp-123")
  messages: Array<{       
    role: "user" | "assistant" | "system";
    content: string;
  }>;
  stream?: boolean;       // Default: false
  chatSessionId?: string; // Continue conversation
}
```

### Parameters

- **model**: Your Chipp application's `appNameId` (format: `appname-123`)
- **messages**: Array of message objects
- **stream**: Enable streaming (optional)
- **chatSessionId**: Continue existing session (optional)

## Response

### Success (200)

```json
{
  "chatSessionId": "550e8400-e29b-41d4-a716-446655440000",
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699451234,
  "model": "myapp-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 (app) |
| 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 \"invalidapp-999\""
}
```

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

## Sessions

### New Session
Omit `chatSessionId` to start fresh.

### Continue Session
Include `chatSessionId` from previous response. Previous messages are loaded automatically.

## Requirements

- Pro plan or higher (Free accounts cannot access the API)
- Valid API key from your application's Share tab