> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onefirewall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Usage Guide

> Complete guide to using the Secure AI Gateway API.

## 🚀 Quick Start

### 1. Get Your API Key

1. Go to **Profile** page in the app.
2. Click **"Create API Key"**.
3. Give it a name (e.g., "Automation Script").
4. **Copy the key immediately** (you won't see it again!).

### 2. Make Your First Request

The endpoint is OpenAI-compatible, meaning you can use standard LLM libraries or simple `curl` commands.

```bash theme={null}
curl https://onefirewall.ai/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'
```

## 📋 API Reference

### Endpoint: `POST /api/v1/chat/completions`

| Parameter     | Type    | Default           | Description                                                                |
| :------------ | :------ | :---------------- | :------------------------------------------------------------------------- |
| `model`       | string  | **REQ**           | Identifier (e.g., `openai/gpt-4o`, `grok/grok-beta`)                       |
| `messages`    | array   | **REQ**           | Chat history (OpenAI format)                                               |
| `system`      | string  | *Default Persona* | Custom system prompt. If provided, it overrides all default behavior.      |
| `stream`      | boolean | `false`           | Enable/disable real-time streaming.                                        |
| `web_search`  | boolean | `true`\*          | Enables tools. Defaults to `true` unless a custom `system` prompt is used. |
| `pii`         | string  | `disabled`        | Security mode: `disabled`, `obfuscate`, or `block`.                        |
| `temperature` | number  | `0.7`             | Controls randomness (0.0 to 2.0).                                          |

***

## 🐍 Python Implementation Examples

### Standard (Non-Streaming)

```python theme={null}
import requests

API_KEY = "your_key_here"
URL = "https://onefirewall.ai/api/v1/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

data = {
    "model": "openai/gpt-4o",
    "web_search": True,
    "pii": "obfuscate",
    "messages": [
        {"role": "user", "content": "Who won the Super Bowl recently?"}
    ]
}

response = requests.post(URL, headers=headers, json=data)
print(response.json()["choices"][0]["message"]["content"])
```

### Advanced Streaming

Recommended for a better user experience in CLI or UI applications.

```python theme={null}
import requests
import sys

API_KEY = "your_key_here"
URL = "https://onefirewall.ai/api/v1/chat/completions"

data = {
    "model": "openai/gpt-4o",
    "stream": True,
    "messages": [{"role": "user", "content": "Write a long essay on AI ethics"}]
}

# Request with stream=True
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
response = requests.post(URL, headers=headers, json=data, stream=True)

# Flush output to console in real-time
sys.stdout.reconfigure(encoding='utf-8')
for chunk in response.iter_content(chunk_size=None):
    if chunk:
        print(chunk.decode('utf-8'), end="", flush=True)
```

***

## JavaScript/Node.js Example

```javascript theme={null}
const API_KEY = "sk-YOUR-KEY-HERE";
const URL = "https://onefirewall.ai/api/v1/chat/completions";

const response = await fetch(URL, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "openai/gpt-4o",
    messages: [
      { role: "user", content: "Hello!" }
    ]
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

***

## Tips

1. **Save Your API Key**: You only see it once during creation
2. **Use HTTPS in Production**: All examples use `https://onefirewall.ai` for secure access.
3. **Monitor Usage**: Check your API key stats in the Profile page
4. **Choose Security Level**: Set `pii` based on your needs:
   * Development: `"disabled"` (default)
   * Production: `"obfuscate"` (recommended)
   * High security: `"block"`
5. **Model Selection**: Use the same models available in the chat UI
6. **Custom Prompts**: When you provide a `system` prompt, it's used exclusively (no mixing with app prompts)
7. **API Independence**: The API works independently of team UI settings by design

***

## Support

* View your API keys: Go to **Profile** page
* Delete a key: Click the trash icon next to the key
* Track usage: See request count and last used date in the key list

Enjoy building on top of the secure-ai-gateway! 🚀