Documentation

API reference

The Open Voice Shield REST API is served under /api on your platform host and authenticates with either a bearer token or an API key sent as X-API-Key. This page lists every customer-facing endpoint with its parameters, request and response shapes and the errors it raises.

Base URL and versioning#

Every path below is served under /api on your platform host, so GET /calls is GET https://your-ovs-host.example/api/calls. The interactive explorer is at /api/docs and the machine-readable schema at /api/openapi.json — that schema is what this page is generated from, so the two cannot disagree.

Requests and responses are JSON unless a row below says otherwise. Timestamps are UTC, ISO 8601. Identifiers are UUIDs. Lists take limit and offset and return a total, so you can page without losing rows.

Authentication#

There are two ways to authenticate, and they are interchangeable on every endpoint marked Bearer or API key:

Bearer token

Authorization: Bearer <access token>. You get one from POST /auth/login or POST /auth/signup. It is short-lived; a browser session renews it with POST /auth/refresh. Use this for a person at a screen.

API key

X-API-Key: <key>. It does not expire and is the right credential for a script, a switch integration or a scheduled job.

Create a key with POST /auth/api-keys as the account owner. The full key is in that one response and is stored only as a hash — it can never be shown again. Lose it and you mint a new one and revoke the old. A key acts as the user who minted it: revoke it with DELETE /auth/api-keys/{key_id}, or deactivate that user, and it stops working at once.

Errors#

An error is a JSON body with a detail field and one of the status codes below. The Errors column on each endpoint lists only what that handler raises: 401 on a bad or missing credential and 422 on a malformed parameter apply everywhere and are not repeated row by row.

Authentication, sessions and keys#

Create an account, sign in, rotate a session and mint the API keys your own systems use. A key is minted by a signed-in owner and is shown once.

API=https://your-ovs-host.example

TOKEN=$(curl -s -X POST $API/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ops@acme.example","password":"correct-horse-battery"}' \
  | sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p')

curl -s -X POST $API/api/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"noc-integration"}'
# 201 {"id":"...","name":"noc-integration","prefix":"ovs_...","key":"ovs_...","revoked_at":null}

Users on your account#

Every person who signs in to your account has a user row. Owners invite, rename and deactivate; members can read the list.

curl -s -X POST $API/api/customer/users \
  -H "X-API-Key: $OVS_KEY" -H 'Content-Type: application/json' \
  -d '{"email":"analyst@acme.example","name":"Night shift"}'

Trunk, whitelist, destinations and routing#

The connection itself: the address your switch sends to, the source addresses allowed to send, where a call goes next, and the prefix rules that choose between destinations.

curl -s $API/api/customer/network-info -H "X-API-Key: $OVS_KEY"

curl -s -X POST $API/api/customer/ips \
  -H "X-API-Key: $OVS_KEY" -H 'Content-Type: application/json' \
  -d '{"cidr":"203.0.113.7/32","label":"Toronto SBC"}'

Calls and analysis#

Every call that traversed the platform, its verdict, its transcript, its recording, its SIP flow and a self-contained evidence bundle.

curl -s "$API/api/calls?min_probability=70&limit=20" -H "X-API-Key: $OVS_KEY"

curl -s $API/api/calls/$CALL_ID/analysis -H "X-API-Key: $OVS_KEY"

Sharing a call outside your account#

A password-protected link to one call, for a carrier or a customer who has no account. The owner side is authenticated; the reader side is not.

curl -s -X POST $API/api/calls/$CALL_ID/share \
  -H "X-API-Key: $OVS_KEY" -H 'Content-Type: application/json' \
  -d '{"expires_in_hours":72,"label":"carrier dispute"}'
# 201 — "password" is in this response and in no other

curl -s -X POST $API/api/public/shares/$TOKEN/unlock \
  -H 'Content-Type: application/json' -d '{"password":"..."}'

curl -s $API/api/public/shares/$TOKEN -H "X-Share-Token: $VIEW_TOKEN"

Cases#

The investigation record attached to a call: title, severity, status, assignee and a comment thread.

CASE=$(curl -s -X POST $API/api/cases \
  -H "X-API-Key: $OVS_KEY" -H 'Content-Type: application/json' \
  -d '{"title":"Wangiri from +1 555","severity":"high","call_id":"'$CALL_ID'"}')

curl -s -X POST $API/api/cases/$CASE_ID/comments \
  -H "X-API-Key: $OVS_KEY" -H 'Content-Type: application/json' \
  -d '{"body":"Carrier notified."}'

Automation and controlled numbers#

Rules that act on a verdict without a human — block or divert a number for a set time — and the table of numbers currently under control.

curl -s -X POST $API/api/automation/rules \
  -H "X-API-Key: $OVS_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"auto-block","min_probability":90,"action":"block","duration_hours":24}'

curl -s $API/api/automation/controls -H "X-API-Key: $OVS_KEY"

Alerts and webhooks#

Push a verdict out: e-mail alert rules with their own thresholds, and one signed HTTP webhook for your own systems.

curl -s -X PUT $API/api/customer/webhook \
  -H "X-API-Key: $OVS_KEY" -H 'Content-Type: application/json' \
  -d '{"url":"https://noc.acme.example/hooks/ovs","secret":"a-long-random-string"}'

curl -s -X POST $API/api/customer/webhook/test -H "X-API-Key: $OVS_KEY"

Plans, balance and payments#

What the plans are, what you are on, what you have spent and how to add credit or subscribe by card.

curl -s $API/api/plans

curl -s $API/api/customer/balance -H "X-API-Key: $OVS_KEY"

Dashboard, statistics and live calls#

Aggregates for a dashboard, and the calls that are in progress right now.

curl -s "$API/api/customer/dashboard?days=7" -H "X-API-Key: $OVS_KEY"

curl -s $API/api/customer/live-calls -H "X-API-Key: $OVS_KEY"

Service health#

One unauthenticated endpoint to poll from your own monitoring.

curl -s $API/api/health
# {"status":"ok",...}

Objects#

Every object named above, with its fields as the API returns and accepts them. A field marked or null can be absent.

Generated from the platform's own API schema on 2026-08-27: 81 operations over 66 paths, and 87 objects. Operator-only endpoints are not part of this reference and never appear here.