Quickstart

Get an API key with device login, then make your first chat call.

You'll go from an empty terminal to your first model response against the kavi tier. Every request in this guide goes to https://api.cruxy.ai.

1. Start device login

Ask the gateway for a device code. This endpoint needs no authentication.

curl -X POST https://api.cruxy.ai/api/v1/device/code

You get back a user_code to type, a URL to approve it, and the device_code your client polls with.

{
  "device_code": "cxy_dev_QK3f...redacted",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://cruxy.ai/device",
  "verification_uri_complete": "https://cruxy.ai/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

2. Approve in the browser

Open verification_uri_complete and approve the request. The user_code (WDJB-MJHT) is pre-filled; if you open the plain verification_uri instead, type it in by hand. You have expires_in seconds (600 = ten minutes) to finish.

3. Poll for the key

Poll the token endpoint with your device_code, waiting interval seconds (5) between attempts.

curl -X POST https://api.cruxy.ai/api/v1/device/token \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "cxy_dev_QK3f...redacted" }'

{
  "code": "authorization_pending",
  "error": "authorization_pending",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Once approved, the same request returns 200 with your key.

{
  "access_token": "cxy_live_...redacted",
  "token_type": "bearer",
  "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_id": "6f9c1e2a-1b2c-4d5e-8f90-1a2b3c4d5e6f",
  "expires_at": "2026-10-20T12:00:00.000Z",
  "org": {
    "id": "8c1a5b3e-2d4f-4a6b-9c8d-0e1f2a3b4c5d",
    "name": "Acme Corp",
    "role": "member"
  }
}

Export it into your shell. Never commit a key to source control.

export CRUXY_API_KEY="cxy_live_..."

For the full flow (every polling error code, verifying the key, and key hygiene), see Get your API key.

4. Make your first call

Send a prompt to the kavi tier. stream: false, which is also the default, asks for a single JSON response instead of a stream, so there is one block to read on a first call.

curl https://api.cruxy.ai/api/v1/chat \
  -H "Authorization: Bearer $CRUXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kavi",
    "stream": false,
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

const res = await fetch('https://api.cruxy.ai/api/v1/chat', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRUXY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'kavi',
    stream: false,
    messages: [{ role: 'user', content: 'Hello' }],
  }),
})
 
const completion = await res.json()
console.log(completion)

The response is an OpenAI-shaped chat completion. Alongside the standard fields, Cruxy adds a namespaced cruxy block carrying the request_id and the cost of the call; a vanilla OpenAI client ignores it. See Chat for the streaming form and the full request options.

Where to go next