Quickstart

This guide takes you from zero to a live API call. We’ll create a key, verify it against the Vox health check, and place a test call.

Create an API key

Sign in to the Cloove Dashboard .
Go to Developer → API keys.
Click Create key, choose the Test environment, and select the scopes you need. For this guide, pick vox:read, vox:calls:read, and vox:calls:create.
Copy the secret key (clv_test_sk_…).

The secret is shown only once. Store it somewhere safe before leaving the dialog.

Verify your key

Call the Vox health check. A 200 confirms your key is valid and tells you which business and environment it’s bound to.

cURL


curl https://api.clooveai.com/v1/vox/health \
  -H "Authorization: Bearer clv_test_sk_your_key_here"

Node.js


const res = await fetch('https://api.clooveai.com/v1/vox/health', {
  headers: { Authorization: 'Bearer clv_test_sk_your_key_here' },
})
const body = await res.json()
console.log(body)

Python


import requests
 
res = requests.get(
    "https://api.clooveai.com/v1/vox/health",
    headers={"Authorization": "Bearer clv_test_sk_your_key_here"},
)
print(res.json())


{
  "message": "Vox API ready",
  "data": {
    "businessId": "b1a2c3d4-...",
    "environment": "test",
    "keyId": "k1a2c3d4-..."
  }
}

Place a test call

Find a voice number ID (GET /v1/vox/numbers) and an agent ID (GET /v1/vox/agents), then queue an outbound call. Pass an Idempotency-Key so a retry never places two calls.

cURL


curl -X POST https://api.clooveai.com/v1/vox/calls \
  -H "Authorization: Bearer clv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2e1c7a-quickstart-001" \
  -d '{
    "customer_phone": "+2348012345678",
    "customer_name": "Ada Lovelace",
    "purpose": "order_confirmation",
    "context": "Confirm order #1234 for NGN 5,000 and mention delivery by Friday.",
    "business_voice_number_id": "your-number-id",
    "ai_agent_id": "your-agent-id"
  }'

The call is queued and processed asynchronously. To follow its progress, either poll GET /v1/vox/calls or - better - subscribe to vox.call.* webhooks.

Where to go next

Lock down your key - add an IP allowlist and set an expiry. See Authentication.
Handle errors and limits - see API conventions.
React to events - set up Webhooks instead of polling.
Go to production - swap your clv_test_… key for a clv_live_… key. Nothing else in your code changes.

Best practices

Separate keys per environment and service. Never use a live key in development.
Grant least privilege. Only the scopes a service actually needs.
Restrict by IP for server-side keys, and rotate keys periodically.
Make writes idempotent. Always send an Idempotency-Key on POSTs that create things (calls, orders, withdrawals).
Verify webhook signatures and respond 2xx quickly, doing real work asynchronously.