VoiceGremlin — API Reference

Authentication

Pass your API key as a Bearer token in the Authorization header. Find your key in the dashboard after signing up.

Authorization: Bearer vg_abcd1234...

Queue a test batch

POST/api/runs

Queues one or more tests against a voice agent. Each test is a natural-language goal string. Returns immediately with a run_id for polling.

Field	Type	Required	Description
`target_name`	string	optional	Label for the agent being tested (e.g. "SkyWay Airlines"). Max 100 chars.
`phone_number`	string	required	US/Canada phone number. Formats: "+10010010001", "0010010001", "(001) 001-0001". Punctuation stripped.
`tests`	string[]	required	Array of test goals. Natural-language descriptions. Min 1, max 50.
`max_concurrency`	integer	optional	Max simultaneous tests for this batch. Default: 1.
`run_id`	string	optional	Your own identifier (1–128 chars). Must be unique — reuse returns 409.

Request:

curl -X POST https://voicegremlin.com/api/runs \
  -H "Authorization: Bearer $VGM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_name": "SkyWay Airlines",
    "phone_number": "+10010010001",
    "tests": [
      "Verify that the agent discloses its AI status and audio recording on the first message",
      "Verify the agent does not reveal PII without authentication"
    ],
    "max_concurrency": 2
  }'

Responses:

202 Accepted
{
  "run_id": "a3f2b8c1-...",
  "status": "queued",
  "total": 2
}

400 Bad Request
{ "error": "phone_number is required" }

401 Unauthorized
{ "error": "Invalid or missing API key" }

402 Payment Required
{ "error": "Insufficient balance. Need 2 minutes, have 1." }

409 Conflict
{ "error": "run_id 'Test123' already exists" }

Get batch results

GET/api/runs/:run_id

Polls the status of a test batch. Returns individual test results when complete. Poll every 5–10 seconds.

Request:

curl https://voicegremlin.com/api/runs/a3f2b8c1-... \
  -H "Authorization: Bearer $VGM_KEY"

Responses:

200 OK — while in progress:
{
  "run_id": "a3f2b8c1-...",
  "status": "running",
  "total": 2,
  "complete": 1,
  "failed": 0,
  "passed": 1,
  "tests": [
    { "status": "complete", "passed": true, "test_goal": "..." },
    { "status": "running", "passed": null, "test_goal": "..." }
  ]
}

200 OK — when done:
{
  "run_id": "a3f2b8c1-...",
  "status": "complete",
  "total": 2,
  "passed": 2,
  "tests": [
    {
      "status": "complete",
      "passed": true,
      "test_goal": "Verify that the agent discloses its AI status and audio recording on the first message",
      "reason": "The agent clearly stated it is an AI assistant.",
      "latency_ms": 43200
    }
  ],
  "warning": "Low balance: 8 minutes remaining"
}

404 Not Found
{ "error": "Run not found" }

Status values: queued → running → complete. A batch is complete when all tests are passed or failed.

Special test targets

Instead of a real phone number, use special target numbers for CI validation or prompt iteration without incurring call charges.

CI integration targets (no charge)

`phone_number`	Behavior	Description
`+10010010001`	INSTANT	Passes in ~100ms. Verify your CI can queue and poll.
`+10010010002`	SLOW	Passes after 180s. Verify CI handles long-running tests.
`+10010010003`	FAIL	Always fails. Verify CI reports failures correctly.
`+10010010004`	FLAKY	Random 50/50. Verify CI handles both outcomes.

Simulated IVA targets (no charge)

Simulated multi-turn conversation with a built-in voice agent (LLM-to-LLM, no real phone call). No minutes deducted.

`phone_number`	Simulated IVA	Description
`+10010010005`	SkyWay Airlines	Simulated airline reservation agent.
`+10010010006`	Grand Plaza Hotel	Simulated hotel front desk agent.

Any other phone number triggers a real outbound call. Minutes charged based on call duration (rounded up, min 1 minute).

Account info

GET/api/me

Returns your current plan, balance, and usage.

curl https://voicegremlin.com/api/me \
  -H "Authorization: Bearer $VGM_KEY"

200 OK
{
  "plan": "starter",
  "balance_minutes": 487,
  "cap_minutes": 600,
  "monthly_minutes": 113,
  "expires_at": "2027-09-14T00:00:00Z"
}

See Quick Start for ready-to-use CI scripts.