API Reference

Complete REST API endpoint reference for CallMeter, including authentication, resource operations, request/response formats, pagination, and rate limits.

The CallMeter REST API provides programmatic access to projects, tests, test runs, probes, and registrars. Use the API to automate test execution, integrate with CI/CD pipelines, build custom dashboards, and export data.

API in Active Development

The API reference is being expanded. The endpoints documented below represent the current stable API surface. Contact support@callmeter.io for additional endpoint documentation or to request new API capabilities.

Base URL

All API requests use the following base URL:

https://callmeter.io/api/v1

Authentication

Authenticate every request by including your API key in the Authorization header using the Bearer scheme:

curl -H "Authorization: Bearer cmk_your_api_key_here" \
  https://callmeter.io/api/v1/projects

API keys use the cmk_ prefix followed by 32 hexadecimal characters. Generate keys from API Keys in the project sidebar. See API Authentication for detailed instructions on key creation, permissions, and security best practices.

Keep Your API Key Secret

API keys grant full access according to the creating user's permissions. Never commit API keys to version control, expose them in client-side code, or share them in unsecured channels. Use environment variables or a secrets manager.

Request Format

Content-Type: application/json for request bodies
Accept: application/json for all responses
Method: Standard HTTP methods (GET, POST)
URL parameters: Path parameters use {param} notation (e.g., /projects/{projectId})
Query parameters: Used for filtering, pagination, and sorting

Response Format

All responses return JSON wrapped in a consistent envelope with data and meta fields.

Success response (single resource):

{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Production Stress Test",
    "status": "COMPLETED",
    "createdAt": "2026-01-15T10:30:00Z"
  },
  "meta": {
    "requestId": "uuid"
  }
}

Success response (list):

{
  "data": [
    { "id": "abc123", "name": "Production Stress Test" },
    { "id": "def456", "name": "Staging Quality Check" }
  ],
  "meta": {
    "requestId": "uuid",
    "pagination": {
      "page": 1,
      "perPage": 25,
      "total": 42,
      "totalPages": 2
    }
  }
}

Error response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  },
  "meta": {
    "requestId": "uuid"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created (resource created successfully)
400	Bad Request (invalid parameters)
401	Unauthorized (missing or invalid API key)
403	Forbidden (insufficient permissions)
404	Not Found (resource does not exist)
422	Unprocessable Entity (validation error)
429	Too Many Requests (rate limit exceeded)
500	Internal Server Error

Pagination

List endpoints use offset-based pagination.

Query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`per_page`	integer	25	Number of items per page (max 100)

Example:

# First page
curl -H "Authorization: Bearer cmk_..." \
  "https://callmeter.io/api/v1/projects?page=1&per_page=10"

# Second page
curl -H "Authorization: Bearer cmk_..." \
  "https://callmeter.io/api/v1/projects?page=2&per_page=10"

When pagination.page equals pagination.totalPages, there are no more results.

Rate Limits

API requests are rate-limited per API key. When the rate limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating when to retry.

Plan	Requests per minute
Free	10
Basic	60
Pro	120
Enterprise	Custom

Projects

Projects are workspaces that group related tests, registrars, media files, and probes.

List Projects

List all projects accessible to the authenticated user.

GET /projects

Query parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number (default 1)
`per_page`	integer	No	Items per page (default 25, max 100)

Response: 200 OK

{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "slug": "production",
      "name": "Production",
      "description": "Production SIP infrastructure testing",
      "testCount": 12,
      "probeCount": 3,
      "registrarCount": 2
    }
  ],
  "meta": {
    "requestId": "uuid",
    "pagination": { "page": 1, "perPage": 25, "total": 1, "totalPages": 1 }
  }
}

Get Project

Retrieve a project by ID.

GET /projects/{projectId}

Response: 200 OK with full project details including test count, probe count, and registrar count.

Tests

Tests represent reusable SIP testing scenario configurations. Each test can be run multiple times, producing independent test runs. All test endpoints are scoped under a project.

List Tests

List all tests in a project.

GET /projects/{projectId}/tests

Query parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number (default 1)
`per_page`	integer	No	Items per page (default 25, max 100)

Response: 200 OK

{
  "data": [
    {
      "id": "abc123",
      "name": "Production Stress Test",
      "durationSeconds": 120,
      "totalEndpoints": 500,
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "requestId": "uuid",
    "pagination": { "page": 1, "perPage": 25, "total": 1, "totalPages": 1 }
  }
}

Get Test

Retrieve a single test configuration by ID.

GET /projects/{projectId}/tests/{testId}

Response: 200 OK with full test configuration including groups, codecs, and media settings.

Run Test

Start a new execution of a test. Creates a test run and begins the allocation and execution process.

POST /projects/{projectId}/tests/{testId}/run

Response: 201 Created

{
  "data": {
    "id": "xyz789",
    "testId": "abc123",
    "status": "PENDING",
    "createdAt": "2026-01-15T11:00:00Z"
  },
  "meta": {
    "requestId": "uuid"
  }
}

The run transitions through PENDING, QUEUED, RUNNING, and then either COMPLETED, FAILED, or CANNOT_RUN_FOR_NOW.

Test Runs

Test runs represent individual executions of a test. Each run has its own status, endpoints, and metrics. All test run endpoints are scoped under a project.

List Test Runs

List test runs in a project.

GET /projects/{projectId}/test-runs

Query parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number (default 1)
`per_page`	integer	No	Items per page (default 25, max 100)

Response: 200 OK

{
  "data": [
    {
      "id": "xyz789",
      "testId": "abc123",
      "status": "COMPLETED",
      "startedAt": "2026-01-15T11:00:01Z",
      "completedAt": "2026-01-15T11:02:35Z"
    }
  ],
  "meta": {
    "requestId": "uuid",
    "pagination": { "page": 1, "perPage": 25, "total": 1, "totalPages": 1 }
  }
}

Get Test Run

Retrieve a test run by ID, including status and summary statistics.

GET /projects/{projectId}/test-runs/{testRunId}

Response: 200 OK

{
  "data": {
    "id": "xyz789",
    "testId": "abc123",
    "status": "COMPLETED",
    "startedAt": "2026-01-15T11:00:01Z",
    "completedAt": "2026-01-15T11:02:35Z",
    "summary": {
      "totalEndpoints": 500,
      "registeredCount": 498,
      "registrationFailedCount": 2,
      "inCallCount": 0,
      "completedCount": 498,
      "avgMos": 4.21,
      "avgJitterMs": 8.3,
      "avgPacketLossFraction": 0.12,
      "avgRttMs": 45.2,
      "asr": 99.6,
      "ner": 100.0
    }
  },
  "meta": {
    "requestId": "uuid"
  }
}

List Test Run Endpoints

List endpoints in a test run with their final status and summary metrics.

GET /projects/{projectId}/test-runs/{testRunId}/endpoints

Query parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number (default 1)
`per_page`	integer	No	Items per page (default 25, max 100)

Response: 200 OK

{
  "data": [
    {
      "id": "ep_001",
      "groupIndex": 0,
      "groupName": "Callers",
      "phase": "CLOSED",
      "outcome": "SUCCESS",
      "role": "caller",
      "sipAccount": "user001@sip.example.com"
    }
  ],
  "meta": {
    "requestId": "uuid",
    "pagination": { "page": 1, "perPage": 25, "total": 500, "totalPages": 20 }
  }
}

Probes

Probes are scheduled, continuous monitoring tests. They execute at regular intervals and evaluate quality thresholds.

List Probes

List all probes in a project.

GET /projects/{projectId}/probes

Query parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number (default 1)
`per_page`	integer	No	Items per page (default 25, max 100)

Response: 200 OK

{
  "data": [
    {
      "id": "probe_abc123",
      "name": "Production Health Check",
      "status": "HEALTHY",
      "intervalMinutes": 15,
      "lastExecutionAt": "2026-01-15T11:00:00Z",
      "nextExecutionAt": "2026-01-15T11:15:00Z"
    }
  ],
  "meta": {
    "requestId": "uuid",
    "pagination": { "page": 1, "perPage": 25, "total": 1, "totalPages": 1 }
  }
}

Get Probe

Retrieve a probe by ID, including current health status, configuration, and threshold settings.

GET /projects/{projectId}/probes/{probeId}

Response: 200 OK with full probe configuration, current health status, last execution timestamp, and threshold definitions.

Run Probe

Trigger an immediate execution of a probe, outside its regular schedule.

POST /projects/{projectId}/probes/{probeId}/run

Response: 201 Created with the queued probe execution details.

Registrars

Registrars represent SIP server configurations used by tests and probes.

List Registrars

List all registrars configured for a project.

GET /projects/{projectId}/registrars

Query parameters:

Parameter	Type	Required	Description
`page`	integer	No	Page number (default 1)
`per_page`	integer	No	Items per page (default 25, max 100)

Response: 200 OK

{
  "data": [
    {
      "id": "reg_abc123",
      "name": "Production SBC",
      "uri": "sip:pbx.example.com",
      "transport": "UDP"
    }
  ],
  "meta": {
    "requestId": "uuid",
    "pagination": { "page": 1, "perPage": 25, "total": 1, "totalPages": 1 }
  }
}

Error Handling

All error responses follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid page parameter"
  },
  "meta": {
    "requestId": "uuid"
  }
}

Common Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Insufficient permissions for this operation
`NOT_FOUND`	404	Resource does not exist or is not accessible
`VALIDATION_ERROR`	422	Request body failed validation
`RATE_LIMITED`	429	Rate limit exceeded. Check `Retry-After` header.
`INTERNAL_ERROR`	500	Unexpected server error. Contact support if persistent.

CI/CD Integration Pattern

A common pattern for integrating CallMeter into deployment pipelines:

# 1. Trigger a test run
RUN_ID=$(curl -s -X POST \
  -H "Authorization: Bearer $CALLMETER_API_KEY" \
  "https://callmeter.io/api/v1/projects/$PROJECT_ID/tests/$TEST_ID/run" \
  | jq -r '.data.id')

# 2. Poll until complete
while true; do
  STATUS=$(curl -s \
    -H "Authorization: Bearer $CALLMETER_API_KEY" \
    "https://callmeter.io/api/v1/projects/$PROJECT_ID/test-runs/$RUN_ID" \
    | jq -r '.data.status')

  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
    break
  fi
  sleep 10
done

# 3. Check quality gate
MOS=$(curl -s \
  -H "Authorization: Bearer $CALLMETER_API_KEY" \
  "https://callmeter.io/api/v1/projects/$PROJECT_ID/test-runs/$RUN_ID" \
  | jq -r '.data.summary.avgMos')

if (( $(echo "$MOS < 3.5" | bc -l) )); then
  echo "Quality gate FAILED: MOS $MOS is below 3.5"
  exit 1
fi

echo "Quality gate PASSED: MOS $MOS"

See CI/CD Integration for complete pipeline examples.

API Authentication -- API key management
CI/CD Integration -- Pipeline integration examples
Probe Health States -- Probe health evaluation

API Reference

On this page