Quick Start — VoiceGremlin

Once you have your API key, use these example CI scripts or point your coding assistant at our public GitHub repo, which has all of the same information on this page.

Run a test

Set VGM_KEY to your VoiceGremlin API key (found in the dashboard under Auth) in your CI secret store, or pass it on the command line:

Bash

PowerShell

Python

# VGM_KEY is set from your CI secret store
VGM_KEY="vg_xxx" bash <(curl -s https://raw.githubusercontent.com/voicegremlin/voicegremlin-iva-test-automation/main/voicegremlin-ci.sh) "SkyWay Airlines" "+10010010001" "Verify that the agent discloses its AI status and audio recording on the first message" "Verify the agent transfers to a human"

# VGM_KEY is set from your CI secret store
$env:VGM_KEY="vg_xxx"
Invoke-WebRequest https://raw.githubusercontent.com/voicegremlin/voicegremlin-iva-test-automation/main/voicegremlin-ci.ps1 -OutFile voicegremlin-ci.ps1
./voicegremlin-ci.ps1 -Target "SkyWay Airlines" -Phone "+10010010001" -Tests "Verify that the agent discloses its AI status and audio recording on the first message", "Verify the agent transfers to a human"

# VGM_KEY is set from your CI secret store
VGM_KEY="vg_xxx" python3 <(curl -s https://raw.githubusercontent.com/voicegremlin/voicegremlin-iva-test-automation/main/voicegremlin-ci.py) "SkyWay Airlines" "+10010010001" "Verify that the agent discloses its AI status and audio recording on the first message" "Verify the agent transfers to a human"

Implementation guide

Most teams let their AI coding assistant write the CI step. Copy the block below and paste it into your assistant along with instructions like "add a CI step that calls VoiceGremlin":

## VoiceGremlin API

Base URL: https://voicegremlin.com
Auth: Bearer token (env var VGM_KEY)

### Queue a test run
POST /api/runs
Body: {
  "phone_number": "+10010010001",       // required, E.164 format
  "tests": ["Verify the agent..."],     // required, array of strings
  "target_name": "SkyWay Airlines",     // optional, label for the agent
  "max_concurrency": 1,                // optional, default 1
  "run_id": "my-custom-id"             // optional, your own identifier
}
Response 202: { "run_id": "abc123" }

### Get run status
GET /api/runs/:run_id
Response 200: {
  "status": "pending" | "running" | "complete",
  "total": 2,
  "passed": 1,
  "failed": 1,
  "results": [
    { "test_goal": "...", "passed": true, "reason": null },
    { "test_goal": "...", "passed": false, "reason": "Agent did not..." }
  ]
}

### CI behavior
- Poll GET /api/runs/:id every 10s until status == "complete" (timeout 5 min)
- Exit 0 if failed == 0, exit 1 otherwise
- Print failed test goals and reasons on failure

### Example: GitHub Actions step
- name: Voice agent tests
  env:
    VGM_KEY: ${{ secrets.VGM_KEY }}
  run: |
    RESPONSE=$(curl -s -X POST https://voicegremlin.com/api/runs \
      -H "Authorization: Bearer $VGM_KEY" \
      -H "Content-Type: application/json" \
      -d '{"phone_number":"+10010010001","tests":["Verify that the agent discloses its AI status and audio recording on the first message"]}')
    RUN_ID=$(echo "$RESPONSE" | jq -r '.run_id')
    for i in $(seq 1 30); do
      sleep 10
      RESULT=$(curl -s "https://voicegremlin.com/api/runs/$RUN_ID" -H "Authorization: Bearer $VGM_KEY")
      STATUS=$(echo "$RESULT" | jq -r '.status')
      [ "$STATUS" = "complete" ] && break
    done
    echo "$RESULT" | jq -r '.results[] | select(.passed == false) | "  ✗ \(.test_goal): \(.reason)"'
    [ "$(echo "$RESULT" | jq -r '.failed')" -eq 0 ]

For tips on writing test goals that produce reliable results, see our guide: Writing effective Voice Agent tests.