# API Reference

## 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](/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 →](/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 →](/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 →](/04-api-reference/02-errors.md)

## SDK Support

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

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

## Additional Resources

* [**Complete Endpoint Documentation**](/04-api-reference/01-endpoints.md) - Detailed API reference
* [**Error Reference**](/04-api-reference/02-errors.md) - Error codes and troubleshooting
* [**Best Practices**](/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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.halfred.ai/04-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.