Quickstart: First Request

1) Endpoint + Auth

Base URL: https://api.hardcarrx.com
Endpoint: POST /v1/chat/completions
Auth: Authorization: Bearer hxv_... or x-api-key: hxv_... (your Hardcarrx API Key). No x-tenant-id required.

2) Choose your provider-key method

HardCarrx supports two ways to call providers behind the same Hardcarrx API Key. The canonical request fields are provider and optional provider_key.

Method A, stored provider key in HardCarrx (OpenAI example)

curl -X POST https://api.hardcarrx.com/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "messages": [
      {"role": "user", "content": "Reply with exactly: openai docs live"}
    ]
  }'

Use this when your workspace already has a provider key stored in HardCarrx. Send your Hardcarrx API Key, choose the provider, and HardCarrx uses the stored workspace credential.

Method B, send provider key in the request (OpenRouter example)

curl -X POST https://api.hardcarrx.com/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "provider": "openrouter",
    "provider_key": "sk-or-v1-...",
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {"role": "user", "content": "Reply with exactly: openrouter docs live"}
    ]
  }'

Use this when you want BYOK behavior for a single request instead of relying on a stored workspace credential. Do not use legacy fields like llm_provider or llm_api_key. If you still see older examples using hxv_your_project_key, treat that as a compatibility alias example rather than the preferred naming.

3) Read response + cache headers

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

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1763090000,
  "model": "gpt-4.1-mini-2025-04-14",
  "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) Workspace management routes

For workspace-scoped management flows, prefer the new /v1/workspaces route family. Legacy /v1/projects routes remain compatible during migration.

GET    /v1/workspaces
POST   /v1/workspaces
GET    /v1/workspaces/:workspace_id/keys
POST   /v1/workspaces/:workspace_id/keys
POST   /v1/workspaces/:workspace_id/keys/:key_id/revoke
GET    /v1/workspaces/:workspace_id/provider-keys
POST   /v1/workspaces/:workspace_id/provider-keys
DELETE /v1/workspaces/:workspace_id/provider-keys/:provider
GET    /v1/billing/workspaces/:workspace_id/entitlements
GET    /v1/billing/workspaces/:workspace_id/context-quota-policy
PUT    /v1/billing/workspaces/:workspace_id/context-quota-policy

If you still have existing callers on /v1/projects, they do not need to break immediately. New integrations should use the workspace route family.

5) Error codes (MVP)

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