Skip to main content

​
OpenAPI / docs gaps — for the API owner

Compiled 2026-06-16 during a 10-agent pass that deepened every product skill (.mintlify/skills/*) and the matching API doc pages. Throughout, openapi.yaml was treated as the source of truth and docs were corrected to match it. The items below are the opposite case: things the docs assert that openapi.yaml does not define (so they could not be verified), plus internal openapi.yaml inconsistencies. Nothing here was invented in the docs — each entry is either left as documented (and flagged) or needs a spec change.

​
A. Documented but missing from openapi.yaml

These contracts live only in the MDX docs and could not be cross-checked against a schema. Either add them to the spec or confirm/correct the docs.
  1. XML & WebSocket webhook callback payloads — every <Gather>/<Dial>/<Record>/<Conference>/<Redirect> action-callback payload, the answer/hangup webhook params (CallUUID, From, To, Direction, CallStatus, Digits, DialStatus, RecordUrl, …), and the audio-stream status-callback events (StartStream/PlayedStream/StopStream) exist only in docs. The spec is REST-only.
  2. KYC webhooks — events (kyc.initiated/submitted/completed/failed/ session_expired/session_revoked), payload shape, and the X-Vobiz-Signature HMAC-SHA256 contract (secret = parent auth_token) are doc-only.
  3. Trunk webhooks — CallInitiated (with Allowed/Reason) and Hangup (with billsec/MOS) payloads + the signature header/secret are doc-only. (The spec’s billsec/mos belong to the CDR object, a different schema.)
  4. transfer-call — POST /api/v1/Account/{auth_id}/Call/{call_uuid}/ is documented but the spec only defines GET (retrieve-queued) on that path.
  5. Conference member-level Speak — conference/members.mdx links “Speak Text to a Member” / “Stop Speaking to a Member” rows, but no such REST endpoint exists in the spec.
  6. recording/export-historical-recordings — POST /api/v1/Account/{auth_id}/export/recording/ is documented in full but absent from the spec.
  7. Recording DELETE has no doc page/nav — DELETE …/Recording/{recording_id}/ exists in the spec (returns 204) but has no page; documented inline in recording/recording-object.mdx. Consider adding recording/delete-recording.mdx.
  8. Partner endpoints — POST /login (JWT), GET /analytics, GET /accounts/{id}, GET /accounts/{id}/balance, and global GET /transactions, GET /cdrs, GET /cdrs/{call_uuid}, GET /numbers are documented but not in the spec. partner/api.mdx claims 21 endpoints; the spec defines 11.
  9. WhatsApp — the spec has no WhatsApp schemas at all (only a whatsapp_voice_rate pricing field). Also: docs/introduction imply interactive (buttons/lists) and location outbound sends, but the documented send contract accepts only text/template/media — interactive/location may be inbound-only. Needs confirmation + real request examples if outbound is supported.
  10. make-call extra params — ring_url, ring_method, hangup_url, fallback_url, caller_name, send_digits, send_on_preanswer, time_limit, hangup_on_ring, and all machine_detection_*; plus record transcription_url/ callback_method, play length/mix, speak loop/mix — present in docs/ examples but not in the spec request schemas.
  11. No 402 on purchase — purchase-from-inventory only documents 404 (not in inventory) and 500 (failed debit). The expected 402 insufficient_balance is not in the spec; left unverified rather than invented.

​
B. Internal openapi.yaml inconsistencies (spec bugs)

  1. Stale components/schemas/Trunk — uses legacy field names (id, trunk_type, sip_domain, enabled) that don’t match real trunk responses (trunk_id, trunk_domain, trunk_status, trunk_direction, …). Inline examples carry the real shape; docs follow the examples.
  2. Endpoint SIP host mismatch — endpoint list/retrieve examples use registrar.vobiz.ai while the schema/canonical host is sip.vobiz.ai.
  3. IP ACL field name — create example uses cidr_ip, but the schema field is ip_address.
  4. audio_track default — spec says both; a REST doc said inbound (docs aligned to both).
  5. start-stream status — spec 200 (Stream started) vs docs 202 (audio streaming started).
  6. stream codec field — spec request uses audio_format: [pcm, mulaw] while every doc uses content_type (audio/x-l16/audio/x-mulaw;rate=). content_type is the real field; the audio_format enum looks outdated.
  7. phone-number list paging — list-account-phone-numbers request params are limit/offset but the response is paginated with page/per_page/total.
  8. Endpoint username rule — docs/skills say “alphanumeric only” but every spec example username uses underscores (john_doe). Constraint softened to “may be rejected”; true rule unverifiable.

​
C. Navigation suggestions (docs.json, not changed)

  • Trunks group ("root": "trunks") has no trunks/overview.mdx landing page (sub-resources have index pages).
  • Add recording/delete-recording.mdx + nav entry for the existing DELETE endpoint (see A.7).
  • XML Overview group has no root landing page.
  • account-phone-number/assign-subaccount and unassign-subaccount live under the Sub-Accounts nav group, not Phone Numbers (intentional cross-grouping? confirm).