ORAVYS API

Every call carries your API key in the X-API-Key header, or as Authorization: Bearer <key>. A key sent in the query string or in a form field is refused. Create and revoke keys on the API keys page.

# Live key
oravys_live_...

# Test key: on POST /api/v1/analyze it returns a
# sample response without running an analysis
oravys_test_...

X-API-Key: oravys_live_...

# or
Authorization: Bearer oravys_live_...

A voice is biometric data. Every call that sends audio must carry consent=true, or the pair consent_data_processing=true and consent_voice_processing=true. By sending it you attest that the person whose voice is analyzed gave explicit consent (GDPR Art. 9.2.a, BIPA). Without it the API answers 400 consent_required, and the call is not counted against your quota.

The analysis routes require the detect:audio scope on the key. A key without it receives 403 insufficient_permissions. Keys issued before scopes existed keep their access.

All requests go to https://app.oravys.com. Audio is sent as multipart/form-data in the field audio (wav, mp3, flac, m4a, ogg, webm). The full contract is in the OpenAPI specification.

Retries: send an Idempotency-Key header (8 to 128 characters) on POST requests. The same key with the same body within 24 hours returns the first answer; the same key with a different body answers 422 idempotency_conflict. The streamed answer of /api/v1/analyze is not replayed.

Submit a recording as a job, then poll it. Replace the key and the file name.

# Fast verdict
curl -X POST https://app.oravys.com/api/v1/verdict-only \
  -H "X-API-Key: $ORAVYS_API_KEY" \
  -F "audio=@recording.wav" \
  -F "consent=true"

# Full analysis as a job
curl -X POST https://app.oravys.com/api/v1/analyze/async \
  -H "X-API-Key: $ORAVYS_API_KEY" \
  -H "Idempotency-Key: 5f0c2d6e-recording-01" \
  -F "audio=@recording.wav" \
  -F "consent=true"

# Poll until status is completed or failed
curl https://app.oravys.com/api/v1/job/JOB_ID \
  -H "X-API-Key: $ORAVYS_API_KEY"

import os, time, requests

BASE = "https://app.oravys.com"
HEADERS = {"X-API-Key": os.environ["ORAVYS_API_KEY"]}

with open("recording.wav", "rb") as f:
    r = requests.post(
        f"{BASE}/api/v1/analyze/async",
        headers=HEADERS,
        files={"audio": f},
        data={"consent": "true"},
    )
if r.status_code >= 400:
    err = r.json()["error"]
    raise SystemExit(f"{err['code']}: {err['message']}")
job_id = r.json()["job_id"]

while True:
    job = requests.get(f"{BASE}/api/v1/job/{job_id}", headers=HEADERS).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(5)

Each accepted call counts as one API call. Polling or cancelling a job is not counted, and neither is a call refused for missing consent. Beyond the quota the API answers 429 monthly_quota_exceeded until the first day of the next month (UTC).

Short-term rate limits also apply per key (per minute and per day) and answer 429 rate_limit_exceeded with a retry delay. The fast verdict route is limited to 10 calls per hour per key.

Every error of the /api/v1 routes has the same shape. code is stable and meant for programs; message is for people; doc_url points here. The top-level code and message are copies kept for clients written against the former format, where error was a string.

{
  "error": {
    "code": "consent_required",
    "message": "...",
    "doc_url": "https://oravys.com/developers#errors"
  },
  "code": "consent_required",
  "message": "..."
}

On POST /api/v1/analyze, an error that happens after the stream has started arrives in the final JSON line with HTTP 200, "success": false and the original status.