> For the complete documentation index, see [llms.txt](https://docs.halfred.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.halfred.ai/04-api-reference.md).

# API Reference

Complete REST API documentation for Halfred including endpoints, authentication, request/response formats, and error handling.

## Base URL

All API requests should be made to:

```
https://api.halfred.ai/v1/
```

## Authentication

All requests require authentication using an API key in the Authorization header:

```http
Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Learn more: [Authentication Guide](https://docs.halfred.ai/01-getting-started/02-authentication.md)

## Available Endpoints

### Chat Completions

Generate AI responses for conversational applications.

**Endpoint**: `POST /chat/completions`

```bash
curl -X POST "https://api.halfred.ai/v1/chat/completions" \
  -H "Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "standard",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

[View detailed documentation →](https://docs.halfred.ai/04-api-reference/01-endpoints.md#post-chatcompletions)

### List Models

Retrieve available model profiles.

**Endpoint**: `GET /models`

```bash
curl -X GET "https://api.halfred.ai/v1/models" \
  -H "Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

[View detailed documentation →](https://docs.halfred.ai/04-api-reference/01-endpoints.md#models)

## Quick Reference

| Method | Endpoint            | Description               |
| ------ | ------------------- | ------------------------- |
| POST   | `/chat/completions` | Generate chat completions |
| GET    | `/models`           | List available models     |

## Request Format

All POST requests should use `application/json` content type:

```http
POST /v1/chat/completions HTTP/1.1
Host: api.halfred.ai
Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "model": "standard",
  "messages": [...]
}
```

## Response Format

All responses are returned in JSON format:

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "provider": "openai",
  "profile": "standard",
  "choices": [...],
  "usage": {...}
}
```

## Error Handling

The API uses standard HTTP status codes:

| Status Code | Meaning                                 |
| ----------- | --------------------------------------- |
| 200         | Success                                 |
| 400         | Bad Request - Invalid parameters        |
| 401         | Unauthorized - Invalid API key          |
| 403         | Forbidden - Insufficient permissions    |
| 429         | Too Many Requests - Rate limit exceeded |
| 500         | Internal Server Error                   |

[Learn more about errors →](https://docs.halfred.ai/04-api-reference/02-errors.md)

## SDK Support

Instead of making direct HTTP requests, use our official SDKs:

* [Node.js SDK](https://docs.halfred.ai/02-sdk-integration/01-nodejs.md)
* [Python SDK](https://docs.halfred.ai/02-sdk-integration/02-python.md)
* [OpenAI SDK Compatibility](https://docs.halfred.ai/02-sdk-integration/03-openai-compatibility.md)

## Additional Resources

* [**Complete Endpoint Documentation**](https://docs.halfred.ai/04-api-reference/01-endpoints.md) - Detailed API reference
* [**Error Reference**](https://docs.halfred.ai/04-api-reference/02-errors.md) - Error codes and troubleshooting
* [**Best Practices**](https://docs.halfred.ai/05-advanced/01-best-practices.md) - Optimization tips

## Support

Need help with the API?

* **Email**: <support@halfred.ai>
* **Discord**: [Join our community](https://discord.gg/wS2awX4EV7)
* **Status**: [status.halfred.ai](https://status.halfred.ai)
