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:

Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Learn more: Authentication Guide

Available Endpoints

Chat Completions

Generate AI responses for conversational applications.

Endpoint: POST /chat/completions

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 →

List Models

Retrieve available model profiles.

Endpoint: GET /models

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

View detailed documentation →

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:

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:

{
  "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 →

SDK Support

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

• Node.js SDK

• Python SDK

• OpenAI SDK Compatibility

Additional Resources

• Complete Endpoint Documentation - Detailed API reference

• Error Reference - Error codes and troubleshooting

• Best Practices - Optimization tips

Support

Need help with the API?

• Email: [email protected]

• Discord: Join our community

• Status: status.halfred.ai