### Project Setup and Dependency Installation

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Clones the Claude Relay Service repository, navigates into the project directory, installs necessary npm dependencies, and copies example configuration files.

```bash
# Download project
git clone https://github.com/Wei-Shaw/claude-relay-service.git
cd claude-relay-service

# Install dependencies
npm install

# Copy configuration files (Important!)
cp config/config.example.js config/config.js
cp .env.example .env
```

--------------------------------

### Start and Enable Caddy Service

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Commands to validate the Caddy configuration, start the Caddy service, enable it to start on boot, and check its status.

```bash
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl start caddy
sudo systemctl enable caddy
sudo systemctl status caddy
```

--------------------------------

### Install Node.js and Redis on CentOS/RHEL

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Installs Node.js version 18.x and Redis server on CentOS/RHEL systems. This setup is necessary before deploying the Claude Relay Service.

```bash
# Install Node.js
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

# Install Redis
sudo yum install redis
sudo systemctl start redis
```

--------------------------------

### Initialize and Start Claude Relay Service

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Initializes the service, which generates admin account credentials, and then starts the service in the background. Also includes commands to check service status.

```bash
# Initialize
npm run setup # Will randomly generate admin account password info, stored in data/init.json

# Start service
npm run service:start:daemon   # Run in background (recommended)

# Check status
npm run service:status
```

--------------------------------

### Install Caddy Web Server

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Installation commands for Caddy on Ubuntu/Debian and CentOS/RHEL/Fedora systems. Caddy is a web server that automatically handles HTTPS certificate management.

```bash
# Ubuntu/Debian
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# CentOS/RHEL/Fedora
sudo yum install yum-plugin-copr
sudo yum copr enable @caddy/caddy
sudo yum install caddy
```

--------------------------------

### Install Node.js and Redis on Ubuntu/Debian

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Installs Node.js version 18.x and Redis server on Ubuntu/Debian systems. This is a prerequisite for running the Claude Relay Service.

```bash
# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Redis
sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
```

--------------------------------

### Upgrade Claude Relay Service

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Steps to update the Claude Relay Service to the latest version, including pulling new code, handling potential conflicts, installing dependencies, and restarting the service.

```bash
# 1. Navigate to project directory
cd claude-relay-service

# 2. Pull latest code
git pull origin main

# If you encounter package-lock.json conflicts, use the remote version
git checkout --theirs package-lock.json
git add package-lock.json

# 3. Install new dependencies (if any)
npm install

# 4. Restart service
npm run service:restart:daemon

# 5. Check service status
npm run service:status
```

--------------------------------

### Get System Metrics

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Retrieves system-wide metrics including request counts, token usage, costs, account status, API key statistics, and memory usage. Requires an API key for authentication.

```shell
curl -X GET https://your-domain.com/metrics \
  -H "x-api-key: cr_your_key"
```

--------------------------------

### List Webhook Configurations

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Fetches a list of all configured webhooks for the system. Requires an administrator token for authorization. No specific input is required beyond the authentication header.

```shell
curl -X GET https://your-domain.com/admin/webhook/configs \
  -H "Authorization: Bearer admin_token"
```

--------------------------------

### OpenAI Compatible API Request (Bash)

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Supports requests in OpenAI format, routing them to Claude or Gemini backends. This allows for compatibility with tools expecting OpenAI API structure. Requires an API key for authentication.

```bash
# OpenAI format request routed to Claude
curl -X POST https://your-domain.com/openai/claude/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cr_your_api_key" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

# Response:
# {
#   "id": "chatcmpl-123",
#   "object": "chat.completion",
#   "created": 1677652288,
#   "model": "claude-sonnet-4-20250514",
#   "choices": [{
#     "index": 0,
#     "message": {
#       "role": "assistant",
#       "content": "The capital of France is Paris."
#     },
#     "finish_reason": "stop"
#   }],
#   "usage": {
#     "prompt_tokens": 15,
#     "completion_tokens": 8,
#     "total_tokens": 23
#   }
# }
```

--------------------------------

### CLI Commands for API Key Management

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Provides commands for managing API keys through the service's CLI. This includes creating, listing, updating, and deleting API keys, with options for setting names, limits, and permissions.

```bash
# API Key management
npm run cli keys create -- --name "Team Key" --limit 1000 --permissions claude
npm run cli keys list
npm run cli keys update -- --id key-uuid --limit 2000
npm run cli keys delete -- --id key-uuid
```

--------------------------------

### Send OpenAI Chat Completions Request (curl)

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

This snippet demonstrates how to send a POST request to the /openai/v1/chat/completions endpoint to get responses formatted like OpenAI's Codex model. It requires an Authorization header with a Bearer token and a JSON payload specifying the model, messages, and response format.

```curl
curl -X POST https://your-domain.com/openai/v1/chat/completions \
  -H "Authorization: Bearer cr_codex_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [{"role": "user", "content": "Hello"}],
    "response_format": {"type": "responses"}
  }'
```

--------------------------------

### CLI Commands for Account Management

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Enables management of AI service accounts via the CLI. Supports listing accounts, adding new ones with specified types, and refreshing existing account details. Also includes commands for managing Gemini accounts.

```bash
# Account management
npm run cli accounts list
npm run cli accounts add -- --name "Account 1" --type claude-official
npm run cli accounts refresh account-uuid
npm run cli gemini list
npm run cli gemini add -- --name "Gemini Account"
```

--------------------------------

### OpenAI Chat Completions Endpoint

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Interact with Claude models using an OpenAI-compatible chat completions endpoint.

```APIDOC
## POST /openai/v1/chat/completions

### Description
Sends a prompt to a specified Claude model and receives a completion.

### Method
POST

### Endpoint
https://your-domain.com/openai/v1/chat/completions

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., "Bearer cr_codex_key")
- **Content-Type** (string) - Required - application/json

#### Request Body
- **model** (string) - Required - The identifier of the Claude model to use (e.g., "claude-sonnet-4-20250514").
- **messages** (array) - Required - An array of message objects, each with a `role` (user, assistant, system) and `content`.
- **response_format** (object) - Optional - Specifies the desired response format. Example: `{"type": "responses"}`.
```

--------------------------------

### Configure Service and Redis Settings

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Defines the server port and host, along with Redis connection details (host and port), within the `config/config.js` file for the Claude Relay Service.

```javascript
module.exports = {
  server: {
    port: 3000,          // Service port, can be changed
    host: '0.0.0.0'     // Don't change
  },
  redis: {
    host: '127.0.0.1',  // Redis address
    port: 6379          // Redis port
  },
  // Keep other configurations as default
}
```

--------------------------------

### CLI Commands for System Maintenance

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Contains CLI commands for performing routine system maintenance tasks. This includes migrating API key expiry formats, initializing cost tracking data, and updating model pricing information.

```bash
# Maintenance
npm run migrate:apikey-expiry  # Migrate API key expiration format
npm run init:costs  # Initialize cost tracking data
npm run update:pricing  # Update model pricing from remote source
```

--------------------------------

### User Management: Registration, Login, API Keys, and Profile

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Handles user management operations including registration, login, API key creation, and retrieving user profiles. Supports standard JSON requests and JWT authentication.

```bash
# Register a new user
curl -X POST https://your-domain.com/users/register \
  -H "Content-Type: application/json" \
  -d '{ 
    "username": "developer1",
    "email": "dev@example.com",
    "password": "secure_password_123"
  }'

# Response:
# { 
#   "success": true,
#   "userId": "user-uuid",
#   "message": "User registered successfully"
# }

# Login
curl -X POST https://your-domain.com/users/login \
  -H "Content-Type: application/json" \
  -d '{ 
    "username": "developer1",
    "password": "secure_password_123"
  }'

# Response:
# { 
#   "success": true,
#   "token": "jwt_token_here",
#   "user": {
#     "id": "user-uuid",
#     "username": "developer1",
#     "email": "dev@example.com"
#   }
# }

# Create API key for user
curl -X POST https://your-domain.com/users/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jwt_token_here" \
  -d '{ 
    "name": "My Development Key",
    "permissions": "claude",
    "dailyCostLimit": 5.0
  }'

# Get user profile
curl -X GET https://your-domain.com/users/profile \
  -H "Authorization: Bearer jwt_token_here"

```

--------------------------------

### Manage API Keys via REST API (curl)

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

This set of curl commands illustrates how to manage API keys using the REST API. It covers creating a new API key with specified permissions and limits, listing all existing API keys, and retrieving information about a specific key using its API key header.

```bash
# Create API key via REST API
curl -X POST https://your-domain.com/admin/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer admin_token" \
  -d '{
    "name": "Production Key",
    "permissions": "claude",
    "concurrencyLimit": 3,
    "rateLimitWindow": 60,
    "rateLimitRequests": 50,
    "dailyCostLimit": 5.0,
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

# Response:
# {
#   "success": true,
#   "apiKey": "cr_prod_key_here",
#   "keyId": "uuid-1234-5678",
#   "message": "API Key created successfully"
# }

# List all API keys
curl -X GET https://your-domain.com/admin/api-keys \
  -H "Authorization: Bearer admin_token"

# Get key info
curl -X GET https://your-domain.com/api/v1/key-info \
  -H "x-api-key: cr_your_key"
```

--------------------------------

### Pricing Service for Token Usage and Cost Calculation

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Tracks token usage and calculates costs based on model pricing. It supports initializing the service, calculating costs for given usage, and retrieving pricing information for specific models.

```javascript
// Using the pricing service
const pricingService = require('./src/services/pricingService');

// Initialize pricing service
await pricingService.initialize();

// Calculate cost for usage
const usage = {
  input_tokens: 1000,
  output_tokens: 500,
  cache_creation_input_tokens: 200,
  cache_read_input_tokens: 800
};

const model = 'claude-sonnet-4-20250514';
const cost = pricingService.calculateCost(model, usage);

console.log(`Input cost: $${cost.inputCost.toFixed(6)}`);
console.log(`Output cost: $${cost.outputCost.toFixed(6)}`);
console.log(`Cache write cost: $${cost.cacheWriteCost.toFixed(6)}`);
console.log(`Cache read cost: $${cost.cacheReadCost.toFixed(6)}`);
console.log(`Total cost: $${cost.totalCost.toFixed(6)}`);

// Example output:
// Input cost: $0.003000
// Output cost: $0.007500
// Cache write cost: $0.000750
// Cache read cost: $0.000300
// Total cost: $0.011550

// Get model pricing info
const pricing = pricingService.getModelPricing('claude-3-5-sonnet-20241022');
// {
//   input_cost_per_token: 0.000003,
//   output_cost_per_token: 0.000015,
//   cache_creation_input_token_cost: 0.00000375,
//   cache_read_input_token_cost: 0.0000003,
//   max_context_window: 200000
// }

```

--------------------------------

### Manage API Keys Programmatically (JavaScript)

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

This JavaScript code demonstrates how to use the apiKeyService to programmatically manage API keys. It covers generating new keys with various configurations (permissions, rate limits, cost limits, client/model restrictions), verifying existing keys, updating their limits, and retrieving usage statistics.

```javascript
const apiKeyService = require('./src/services/apiKeyService');

// Generate a new API key
const newKey = await apiKeyService.generateApiKey({
  name: 'Development Key',
  description: 'API key for development team',
  permissions: 'all', // 'claude', 'gemini', 'openai', or 'all'
  concurrencyLimit: 5,
  rateLimitWindow: 60, // seconds
  rateLimitRequests: 100,
  rateLimitCost: 1.0, // max $1.00 per window
  dailyCostLimit: 10.0, // max $10 per day
  totalCostLimit: 100.0, // max $100 lifetime
  enableClientRestriction: true,
  allowedClients: ['ClaudeCode', 'Gemini-CLI'],
  enableModelRestriction: true,
  restrictedModels: ['claude-opus-4-20250514'], // blacklist
  expirationMode: 'activation', // 'fixed' or 'activation'
  activationDays: 30,
  activationUnit: 'days'
});

console.log(`API Key: ${newKey.plainKey}`);
// Output: API Key: cr_a1b2c3d4e5f6...

// Verify an API key
const keyData = await apiKeyService.verifyApiKey('cr_a1b2c3d4e5f6...');
console.log(`Key status: ${keyData.isActive}`);
console.log(`Permissions: ${keyData.permissions}`);

// Update API key limits
await apiKeyService.updateApiKey('key-uuid', {
  concurrencyLimit: 10,
  dailyCostLimit: 20.0
});

// Get usage statistics
const usage = await apiKeyService.getUsageStats('key-uuid');
console.log(`Total tokens used: ${usage.totalTokens}`);
console.log(`Total cost: $${usage.totalCost}`);
```

--------------------------------

### OpenAI Compatible API

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Supports OpenAI format requests, routing them to Claude or Gemini backends. Includes chat completions endpoint.

```APIDOC
## POST /openai/{backend}/v1/chat/completions

### Description
Handles chat completion requests in OpenAI format, routed to a specified backend (e.g., Claude).

### Method
POST

### Endpoint
/openai/{backend}/v1/chat/completions

### Parameters
#### Path Parameters
- **backend** (string) - Required - The AI backend to use (e.g., "claude").

#### Header Parameters
- **Content-Type** (string) - Required - Specifies the content type as application/json.
- **Authorization** (string) - Required - Bearer token for authentication (e.g., "Bearer cr_your_api_key").

#### Request Body
- **model** (string) - Required - The model to use (e.g., "gpt-4").
- **messages** (array) - Required - An array of message objects, each with a `role` (system/user/assistant) and `content`.
- **temperature** (number) - Optional - Controls randomness. Values range from 0 to 2.
- **stream** (boolean) - Optional - Set to `false` for non-streaming responses.

### Request Example
```json
{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
  ],
  "temperature": 0.7,
  "stream": false
}
```

### Response
#### Success Response (200)
Returns a JSON object in OpenAI's chat completion format.

#### Response Example
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "claude-sonnet-4-20250514",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 8,
    "total_tokens": 23
  }
}
```
```

--------------------------------

### Webhook Management

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Endpoints for managing webhook configurations and testing webhook functionality.

```APIDOC
## GET /admin/webhook/configs

### Description
Retrieves a list of all configured webhooks.

### Method
GET

### Endpoint
/admin/webhook/configs

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```bash
curl -X GET https://your-domain.com/admin/webhook/configs \
  -H "Authorization: Bearer admin_token"
```

### Response
#### Success Response (200)
- **configs** (array) - A list of webhook configurations.
  - **id** (string) - The unique identifier for the webhook.
  - **url** (string) - The URL to which the webhook events will be sent.
  - **eventTypes** (array) - A list of event types that trigger the webhook.

#### Response Example
```json
{
  "configs": [
    {
      "id": "wh-123",
      "url": "https://example.com/webhook",
      "eventTypes": ["account.status_changed"]
    }
  ]
}
```

## Test Webhook Notification

### Description
This function sends a notification for an account status change to configured webhooks.

### Method
N/A (This is a programmatic example, not a direct HTTP endpoint)

### Endpoint
N/A

### Parameters (Function Arguments)
- **accountId** (string) - Required - The ID of the account.
- **accountName** (string) - Required - The name of the account.
- **oldStatus** (string) - Required - The previous status of the account.
- **newStatus** (string) - Required - The new status of the account.
- **reason** (string) - Optional - The reason for the status change.

### Request Example (Node.js)
```javascript
const webhookNotifier = require('./src/utils/webhookNotifier');

await webhookNotifier.notifyAccountStatusChange(
  'account-uuid',
  'Primary Account',
  'active',
  'rate_limited',
  'Account hit rate limit'
);
```

### Response
This function triggers the sending of a webhook payload. The actual response is from the webhook endpoint receiving the data.

#### Webhook Payload Example
```json
{
  "event": "account.status_changed",
  "timestamp": "2025-11-16T10:30:00Z",
  "data": {
    "accountId": "account-uuid",
    "accountName": "Primary Account",
    "oldStatus": "active",
    "newStatus": "rate_limited",
    "reason": "Account hit rate limit"
  }
}
```
```

--------------------------------

### Set Environment Variables for Claude API Integration

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Configures environment variables `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` to point to the deployed Claude Relay Service, enabling applications to use it as an API endpoint.

```bash
export ANTHROPIC_BASE_URL="http://127.0.0.1:3000/api/" # Fill in your server's IP address or domain according to actual situation
export ANTHROPIC_AUTH_TOKEN="API key created in the backend"
```

--------------------------------

### Configure Caddy Reverse Proxy

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Caddyfile configuration for reverse proxying to a local service (127.0.0.1:3000). It includes settings for streaming responses, passing real IP headers, long timeouts, and security headers.

```caddy
your-domain.com {
    # Reverse proxy to local service
    reverse_proxy 127.0.0.1:3000 {
        # Support streaming responses or SSE
        flush_interval -1

        # Pass real IP
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}

        # Long read/write timeout configuration
        transport http {
            read_timeout 300s
            write_timeout 300s
            dial_timeout 30s
        }
    }

    # Security headers
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        -Server
    }
}
```

--------------------------------

### User Management and Authentication API

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Handles user registration, login, API key management, and LDAP integration.

```APIDOC
## User Management and Authentication API

### Description
APIs for managing users, including registration, authentication (local and LDAP), session management, and API key creation.

### Method
`POST`, `GET`

### Endpoint
- `/users/register`
- `/users/login`
- `/users/api-keys`
- `/users/profile`

### Parameters
#### Path Parameters
None for these endpoints.

#### Query Parameters
None for these endpoints.

#### Request Body (POST /users/register)
- **username** (string) - Required - The desired username.
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

#### Request Body (POST /users/login)
- **username** (string) - Required - The username for login.
- **password** (string) - Required - The user's password.

#### Request Body (POST /users/api-keys)
- **name** (string) - Required - A name for the API key.
- **permissions** (string) - Required - Permissions for the API key (e.g., "claude").
- **dailyCostLimit** (number) - Optional - The daily cost limit for the API key.

#### Headers (for authenticated requests)
- **Authorization**: `Bearer <jwt_token>`
- **Content-Type**: `application/json`

### Request Example (POST /users/register)
```bash
curl -X POST https://your-domain.com/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "developer1",
    "email": "dev@example.com",
    "password": "secure_password_123"
  }'
```

### Response (POST /users/register)
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **userId** (string) - The ID of the newly registered user.
- **message** (string) - A confirmation message.

#### Response Example (POST /users/register)
```json
{
  "success": true,
  "userId": "user-uuid",
  "message": "User registered successfully"
}
```

### Request Example (POST /users/login)
```bash
curl -X POST https://your-domain.com/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "developer1",
    "password": "secure_password_123"
  }'
```

### Response (POST /users/login)
#### Success Response (200)
- **success** (boolean) - Indicates if the login was successful.
- **token** (string) - JWT token for subsequent authenticated requests.
- **user** (object) - User details.
  - **id** (string)
  - **username** (string)
  - **email** (string)

#### Response Example (POST /users/login)
```json
{
  "success": true,
  "token": "jwt_token_here",
  "user": {
    "id": "user-uuid",
    "username": "developer1",
    "email": "dev@example.com"
  }
}
```

### Request Example (POST /users/api-keys)
```bash
curl -X POST https://your-domain.com/users/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jwt_token_here" \
  -d '{
    "name": "My Development Key",
    "permissions": "claude",
    "dailyCostLimit": 5.0
  }'
```

### Request Example (GET /users/profile)
```bash
curl -X GET https://your-domain.com/users/profile \
  -H "Authorization: Bearer jwt_token_here"
```

### LDAP Integration

#### Configuration (Environment Variables)
- `LDAP_ENABLED`: `true` or `false`
- `LDAP_URL`: LDAP server URL (e.g., `ldaps://ldap.example.com:636`)
- `LDAP_BIND_DN`: DN for binding to the LDAP server.
- `LDAP_BIND_PASSWORD`: Password for binding.
- `LDAP_BASE_DN`: Base DN for user searches.
- `LDAP_USER_SEARCH_FILTER`: Filter for user searches (e.g., `(uid={{username}})`)

#### LDAP Login (Client-side Service)
- **Method**: `POST` (Hypothetical service call)
- **Parameters**: `username` (string), `password` (string)
- **Response**: 
  - **success** (boolean)
  - **token** (string)
  - **user** (object) with `id`, `username`, `email`, `authSource` ('ldap')

#### LDAP Login Example (Client-side Service)
```javascript
const userService = require('./src/services/userService');
const result = await userService.loginUser('john.doe', 'ldap_password');
// { success: true, token: 'jwt_token', user: { id: 'user-uuid', username: 'john.doe', email: 'john.doe@example.com', authSource: 'ldap' } }
```
```

--------------------------------

### Pricing and Cost Tracking API

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Calculates costs based on token usage and model pricing information.

```APIDOC
## Pricing and Cost Tracking API

### Description
Provides functionality to track token usage and calculate associated costs based on model-specific pricing.

### Method
`POST` (for `calculateCost`), `GET` (for `getModelPricing`)

### Endpoint
`/pricing/calculate` (Hypothetical - this is a client-side service call, not a direct HTTP API endpoint in the provided text)
`/pricing/models/{modelName}` (Hypothetical - this is a client-side service call, not a direct HTTP API endpoint in the provided text)

### Parameters
#### Request Body (for `calculateCost`)
- **usage** (object) - Required - Token usage details.
  - **input_tokens** (number) - Required - Number of input tokens.
  - **output_tokens** (number) - Required - Number of output tokens.
  - **cache_creation_input_tokens** (number) - Optional - Input tokens for cache creation.
  - **cache_read_input_tokens** (number) - Optional - Input tokens for cache reads.
- **model** (string) - Required - The name of the model used.

### Request Example (calculateCost)
```javascript
{
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "cache_creation_input_tokens": 200,
    "cache_read_input_tokens": 800
  },
  "model": "claude-sonnet-4-20250514"
}
```

### Response (calculateCost)
#### Success Response (200)
- **inputCost** (number) - Cost for input tokens.
- **outputCost** (number) - Cost for output tokens.
- **cacheWriteCost** (number) - Cost for cache write operations.
- **cacheReadCost** (number) - Cost for cache read operations.
- **totalCost** (number) - Total calculated cost.

#### Response Example (calculateCost)
```json
{
  "inputCost": 0.003000,
  "outputCost": 0.007500,
  "cacheWriteCost": 0.000750,
  "cacheReadCost": 0.000300,
  "totalCost": 0.011550
}
```

### Request Example (getModelPricing)
`pricingService.getModelPricing('claude-3-5-sonnet-20241022')`

### Response (getModelPricing)
#### Success Response (200)
- **input_cost_per_token** (number) - Cost per input token.
- **output_cost_per_token** (number) - Cost per output token.
- **cache_creation_input_token_cost** (number) - Cost per input token for cache creation.
- **cache_read_input_token_cost** (number) - Cost per input token for cache reads.
- **max_context_window** (number) - Maximum context window size.

#### Response Example (getModelPricing)
```json
{
  "input_cost_per_token": 0.000003,
  "output_cost_per_token": 0.000015,
  "cache_creation_input_token_cost": 0.00000375,
  "cache_read_input_token_cost": 0.0000003,
  "max_context_window": 200000
}
```
```

--------------------------------

### Configure Environment Variables for Claude Relay Service

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Sets essential environment variables, including JWT secret, encryption key, and Redis connection details, within the .env file for the Claude Relay Service.

```bash
# Generate these two keys randomly, but remember them
JWT_SECRET=your-super-secret-key
ENCRYPTION_KEY=32-character-encryption-key-write-randomly

# Redis configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
```

--------------------------------

### Claude Messages API (Bash)

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Handles Claude API requests, supporting streaming and non-streaming responses. It includes automatic account selection and usage tracking. Requires an API key for authentication.

```bash
curl -X POST https://your-domain.com/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_your_api_key_here" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms"
      }
    ],
    "stream": true
  }'

# Response (Server-Sent Events):
# event: message_start
# data: {"type":"message_start","message":{"id":"msg_123","type":"message"}}
#
# event: content_block_delta
# data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Quantum"}}
#
# event: message_delta
# data: {"type":"message_delta","usage":{"output_tokens":150}}

# Alternative route (same functionality)
curl -X POST https://your-domain.com/claude/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_your_api_key_here" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

# Non-streaming response:
# {
#   "id": "msg_abc123",
#   "type": "message",
#   "role": "assistant",
#   "content": [{"type": "text", "text": "Hello! How can I help you?"}],
#   "model": "claude-3-5-sonnet-20241022",
#   "usage": {
#     "input_tokens": 10,
#     "output_tokens": 8,
#     "cache_creation_input_tokens": 0,
#     "cache_read_input_tokens": 0
#   }
# }
```

--------------------------------

### CLI Commands for User Management

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Manages administrative users for the service through the CLI. Allows for creating new administrators, resetting passwords, and listing existing admin users.

```bash
# User management
npm run cli admin create -- --username admin2
npm run cli admin reset-password -- --username admin
npm run cli admin list
```

--------------------------------

### Unified Scheduler API

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Manages intelligent account selection for Claude requests, supporting sticky sessions and load balancing.

```APIDOC
## Unified Scheduler API

### Description
Provides intelligent account selection for Claude requests, including model support validation, sticky sessions, and load balancing.

### Method
`POST`

### Endpoint
`/selectAccountForApiKey` (Hypothetical - this is a client-side service call, not a direct HTTP API endpoint in the provided text)

### Parameters
#### Request Body
- **apiKeyData** (object) - Required - Data about the API key being used.
  - **id** (string) - Required - The ID of the API key.
  - **permissions** (string) - Required - Permissions associated with the API key.
  - **claudeAccountId** (string) - Optional - If provided, specifies a particular Claude account.
  - **concurrencyLimit** (number) - Optional - The concurrency limit for the API key.
- **sessionHash** (string) - Optional - A hash for maintaining sticky sessions.
- **requestedModel** (string) - Required - The Claude model being requested.

### Request Example
```javascript
{
  "apiKeyData": {
    "id": "key-123",
    "permissions": "all",
    "claudeAccountId": "",
    "concurrencyLimit": 5
  },
  "sessionHash": "session_abc123",
  "requestedModel": "claude-opus-4-20250514"
}
```

### Response
#### Success Response (200)
- **account** (object) - Details of the selected Claude account.
- **accountType** (string) - The type of the selected account.
- **accountService** (object) - The service object for the selected account.

#### Response Example
```json
{
  "account": {
    "id": "account-uuid",
    "name": "Primary Account",
    "accountType": "claude-official",
    "status": "active",
    "concurrencyLimit": 5
  },
  "accountType": "claude-official",
  "accountService": { /* ... */ }
}
```

### Notes
The scheduler automatically handles account status, model validation, concurrency limits, sticky sessions, overload errors (529), and load balancing.
```

--------------------------------

### LDAP Integration for User Authentication

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Configures and performs user login using LDAP authentication. Requires environment variables for LDAP connection details and supports logging in users via their LDAP credentials.

```javascript
// LDAP authentication configuration
// In .env file:
// LDAP_ENABLED=true
// LDAP_URL=ldaps://ldap.example.com:636
// LDAP_BIND_DN=cn=admin,dc=example,dc=com
// LDAP_BIND_PASSWORD=admin_password
// LDAP_BASE_DN=dc=example,dc=com
// LDAP_USER_SEARCH_FILTER=(uid={{username}})

// LDAP login
const userService = require('./src/services/userService');

const result = await userService.loginUser('john.doe', 'ldap_password');
// {
//   success: true,
//   token: 'jwt_token',
//   user: {
//     id: 'user-uuid',
//     username: 'john.doe',
//     email: 'john.doe@example.com',
//     authSource: 'ldap'
//   }
// }

```

--------------------------------

### Gemini API Request (Bash)

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Proxies requests to Google Gemini, handling content generation and streaming responses. It utilizes an API key for authentication and supports OAuth token management.

```bash
# Generate content using Gemini
curl -X POST https://your-domain.com/gemini/v1/models/gemini-2.0-flash-exp:generateContent \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_your_gemini_key" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "Write a Python function to calculate fibonacci numbers"
      }]
    }],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 2048
    }
  }'

# Response:
# {
#   "candidates": [{
#     "content": {
#       "parts": [{"text": "def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)"}],
#       "role": "model"
#     },
#     "finishReason": "STOP"
#   }],
#   "usageMetadata": {
#     "promptTokenCount": 12,
#     "candidatesTokenCount": 45,
#     "totalTokenCount": 57
#   }
# }

# Streaming request
curl -X POST https://your-domain.com/gemini/v1/models/gemini-2.5-flash:streamGenerateContent \
  -H "x-api-key: cr_your_gemini_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Count to 10"}]}]
  }'
```

--------------------------------

### Configure Local Service to Listen Locally

Source: https://github.com/wei-shaw/claude-relay-service/blob/main/README_EN.md

Node.js configuration snippet to set the server to listen only on the local interface (127.0.0.1) when using a reverse proxy like Caddy.

```javascript
// config/config.js
module.exports = {
  server: {
    port: 3000,
    host: '127.0.0.1' // Listen locally only
  }
}
```

--------------------------------

### Gemini API

Source: https://context7.com/wei-shaw/claude-relay-service/llms.txt

Proxies requests to Google Gemini, supporting content generation and streaming with automatic OAuth token management.

```APIDOC
## POST /gemini/v1/models/{model}:generateContent

### Description
Generate content using a specified Gemini model.

### Method
POST

### Endpoint
/gemini/v1/models/{model}:generateContent

### Parameters
#### Path Parameters
- **model** (string) - Required - The Gemini model to use (e.g., "gemini-2.0-flash-exp").

#### Header Parameters
- **Content-Type** (string) - Required - Specifies the content type as application/json.
- **x-api-key** (string) - Required - Your API key for the Claude Relay Service.

#### Request Body
- **contents** (array) - Required - An array of content parts, typically with a `text` field.
- **generationConfig** (object) - Optional - Configuration for generation, including `temperature` and `maxOutputTokens`.

### Request Example
```json
{
  "contents": [{
    "parts": [{
      "text": "Write a Python function to calculate fibonacci numbers"
    }]
  }],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 2048
  }
}
```

### Response
#### Success Response (200)
Returns a JSON object containing candidate responses and usage metadata.

#### Response Example
```json
{
  "candidates": [{
    "content": {
      "parts": [{"text": "def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)"}],
      "role": "model"
    },
    "finishReason": "STOP"
  }],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 45,
    "totalTokenCount": 57
  }
}
```

## POST /gemini/v1/models/{model}:streamGenerateContent

### Description
Generate content using a specified Gemini model with streaming enabled.

### Method
POST

### Endpoint
/gemini/v1/models/{model}:streamGenerateContent

### Parameters
#### Path Parameters
- **model** (string) - Required - The Gemini model to use (e.g., "gemini-2.5-flash").

#### Header Parameters
- **x-api-key** (string) - Required - Your API key for the Claude Relay Service.
- **Content-Type** (string) - Required - Specifies the content type as application/json.

#### Request Body
- **contents** (array) - Required - An array of content parts, typically with a `text` field.

### Request Example
```json
{
  "contents": [{"parts": [{"text": "Count to 10"}]}]
}
```
```