Quickstart: First Request

1) Endpoint + Auth

Base URL: https://api.hardcarrx.com
Endpoint: POST /v1/chat/completions
Auth: Authorization: Bearer hmpk_... or x-api-key: hmpk_... (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)

export HARDCARRX_API_KEY="hxv_your_workspace_api_key"

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

Use this after connecting OpenAI in Dashboard → Providers. 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)

export HARDCARRX_API_KEY="hxv_your_workspace_api_key"
export OPENROUTER_API_KEY="your_provider_api_key"

curl -X POST https://api.hardcarrx.com/v1/chat/completions   -H "Content-Type: application/json"   -H "Authorization: Bearer $HARDCARRX_API_KEY"   -d '{
    "provider": "openrouter",
    "provider_key": "'"$OPENROUTER_API_KEY"'",
    "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. This flow still requires both your Hardcarrx API Key and the provider key. Do not use legacy fields like llm_provider or llm_api_key.

3) Read the response

{
  "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
  }
}

The response follows the OpenAI-style chat completion shape. Use Dashboard → Logs to inspect status, provider, model, latency, cache, memory, and request ID after traffic runs.

4) Workspace management routes

Workspace-scoped management flows use the /v1/workspaces route family.

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

Use workspace IDs for management calls. The legacy project route family is retired.

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 provider or service error