# Quick Start Guide

## Step 1: Create Your Account

1. Go to [halfred.ai](https://halfred.ai) and sign up for a free account using Google, GitHub, or email
2. Verify your email address (if using email sign-up)
3. Log in to your dashboard

## Step 2: Get Your API Key

When you log in for the first time, Halfred automatically:

* Creates a default project for you
* Generates your first API key
* Displays it on your dashboard

**Important:** Copy and securely store your API key immediately - this is the only time you'll see it!

**Your API key will look like this:** `halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx`

⚠️ **Security Note**: Never expose your API key in client-side code or commit it to version control.

### If You Need to Generate a New Key Later

If you lost your key or need to revoke it:

1. Go to your dashboard
2. Find the **"Your Key"** section
3. Click the 3-dots menu (⋮)
4. Select **"Revoke Key & Get New One"**
5. Copy your new key immediately

## Step 3: Add Credits (Optional for Testing)

1. Go to **Credits** in your dashboard
2. Click **"Top up Credits"**
3. Select the amount you want to add ($5 minimum)
4. Complete the secure payment via Stripe

Halfred offers a **free DEV profile** for testing, but it has rate limits and is limited to Lite profile models, making it unsuitable for production use. For production applications:

## Step 4: Make Your First API Call

Choose your preferred method:

### Using the Halfred Node.js SDK

```bash
npm install halfred.ai
```

```javascript
import { Halfred } from "halfred.ai";

const client = new Halfred({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "lite",
    messages: [{ role: "user", content: "Hello, Halfred!" }],
  });

  console.log(completion.choices[0].message.content);
}

main();
```

### Using the Halfred Python SDK

```bash
pip install halfred
```

```python
from halfred import Halfred

client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")

completion = client.chat.completions.create(
    model="lite",
    messages=[
        {"role": "user", "content": "Hello, Halfred!"}
    ]
)

print(completion.choices[0].message.content)
```

### Using cURL (REST API)

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

## Step 5: Understanding the Response

You'll receive a response in this format:

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "provider": "halfred-router",
  "model": "gpt-4o",
  "profile": "LITE",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm Halfred. How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 12,
    "total_tokens": 22
  }
}
```

**Key fields:**

* `choices[0].message.content`: The AI's response
* `usage`: Token consumption for billing
* `profile`: The Halfred profile used
* `provider` & `model`: The actual model that handled your request

## 💡 Tip: Try the Playground

Your Halfred dashboard includes an **advanced Playground interface** where you can:

* Test API requests interactively
* Experiment with different profiles (Lite, Standard, DeepThink, Dev)
* See real-time responses
* View recent logs and request status
* Fine-tune parameters before integrating into your code

This is a great way to explore Halfred's capabilities without writing any code!

## Step 6: Choose Your Profile

Halfred offers different profiles optimized for various use cases:

| Profile       | Use Case                                         | Price per M tokens (output) |
| ------------- | ------------------------------------------------ | --------------------------- |
| **LITE**      | Simple tasks, UI assistants, cost-sensitive apps | $0.50                       |
| **STANDARD**  | Most production applications (recommended)       | $2.50                       |
| **DEEPTHINK** | Complex reasoning, long documents, R\&D          | $12.50                      |
| **DEV**       | Free tier for development and testing            | $0.00                       |

*For the most up-to-date pricing, please refer to the* [*Profile Dashboard*](https://halfred.ai/app/project-profile) *(requires login).*

Learn more about profiles in our [Model Profiles guide](/03-concepts/01-profiles.md).

## What's Next?

Now that you've made your first API call:

1. **Explore SDKs**:
   * [Node.js SDK Documentation](/02-sdk-integration/01-nodejs.md)
   * [Python SDK Documentation](/02-sdk-integration/02-python.md)
2. **Understand Core Concepts**:
   * [Model Profiles](/03-concepts/01-profiles.md)
   * [Pricing & Credits](/03-concepts/02-pricing.md)
   * [Tokens Explained](/03-concepts/03-tokens.md)
3. **Dive Into the API**:
   * [Complete REST API Reference](/04-api-reference/01-endpoints.md)
   * [Error Handling](/04-api-reference/02-errors.md)
4. **Optimize Your Integration**:
   * [Best Practices](/05-advanced/01-best-practices.md)

## Troubleshooting

### "Invalid API key" Error

* Make sure you copied the entire API key including the `halfred_` prefix
* Verify the key hasn't been revoked in your dashboard
* Check that you're using the correct project's API key

### "Insufficient credits" Error

* Add credits in your dashboard under Credits or in your account settings
* Use the free **DEV** profile for testing: `model: "dev"`

### Rate Limit Errors

* Implement exponential backoff retry logic
* Consider upgrading your plan for higher rate limits

## Need Help?

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


---

# 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/01-getting-started/01-quickstart.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.