Quickstart: First Request

1) Endpoint + Auth

Base URL: https://api.hardcarrx.com
Endpoint: POST /v1/chat/completions
Required header: Authorization: Bearer hxv_... (your virtual key)

2) Choose your provider-key method

HardCarrx supports two ways to call providers behind the same virtual key.

Method A, stored provider key in HardCarrx

curl -X POST https://api.hardcarrx.com/v1/chat/completions \
  -H "Authorization: Bearer hxv_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give me 3 launch checklist items for an AI feature."}
    ],
    "temperature": 0.3,
    "max_tokens": 180,
    "provider": "openai"
  }'

Use this when your project already has a provider key stored in HardCarrx. Send your virtual key, choose the provider, and HardCarrx uses the project-level provider credentials.

Method B, send provider key in the request

curl -X POST https://api.hardcarrx.com/v1/chat/completions \
  -H "Authorization: Bearer hxv_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give me 3 launch checklist items for an AI feature."}
    ],
    "temperature": 0.3,
    "max_tokens": 180,
    "provider": "openai",
    "provider_key": "sk-provider-key"
  }'

Use this when you want to pass the provider key directly with the request instead of relying on a stored project credential. Request field names are provider and provider_key(not llm_api_key).

3) Read response + cache headers

HTTP/1.1 200 OK
x-cache-status: HIT
x-hardcarrx: route=openai:gpt-4o-mini; cache=semantic; mem=profile
content-type: application/json

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1763090000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1) Define success metrics..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 68,
    "completion_tokens": 72,
    "total_tokens": 140
  }
}

x-cache-status: HIT / MISS / BYPASS
x-hardcarrx includes selected route and gateway metadata.

4) Error codes (MVP)

• 400 invalid payload (missing model/messages, bad JSON)
• 401 missing or invalid virtual key
• 402 quota/credits exceeded for current plan
• 429 rate limit reached
• 5xx upstream/provider or gateway internal error