Skip to main content

SDKs & OpenAPI

This page is deliberately the least exciting one in this documentation set, because the honest version of it is short.

There is no published VoiceMatrix SDK today

No npm package, no PyPI package. Verified 2026-08-24 by checking what's actually tracked in git on both main and dev: git ls-tree -r origin/main -- sdk/ returns nothing. If you've found a sdk/ folder locally with Python or TypeScript files in it, or seen it mentioned as shipped in an internal note — it exists only on unmerged feature branches (four of them, dating back to 2026-08-09), none merged to the branches that actually deploy. Anyone using it today is using code that isn't in production and isn't reviewed as part of any release.

This is a real gap relative to every competitor referenced in this documentation's own research — Vapi, Retell, and ElevenLabs each ship official Python + TypeScript/JavaScript SDKs at minimum, and Retell additionally ships an MCP server for building agents (not just querying them).

What you can use today: the OpenAPI spec

text
https://api.voicematrix.ai/swagger/doc.json

This spec is real and current — as of this writing it enumerates all 19 real /ext path templates (those 19 paths carry 30 registered method+path routes between them; note the backend's own startup log prints "29 endpoints", which is off by one against the actual registrations — trust the spec and the router, not that log line), and a drift test fails the build if a route exists without a spec entry or vice versa. You can point openapi-generator (or any OpenAPI-compatible client generator) at that URL today and get a working client in your language of choice, with no hand-written SDK required.

Why this page couldn't have said that four months ago

The committed spec file was always valid — but the served endpoint was not. swaggo doesn't serve the committed JSON file directly; it renders a Go template (docs.go) through text/template at request time to fill in .Host and similar fields, and silently returns the unrendered template on a parse error instead of failing. A struct field's doc comment contained a literal {{field}} (documenting webhook payload-template syntax, in a comment — see the warning still in webhooks_dto.go telling future authors not to repeat this), which Go read as a template action calling an undefined function. The result: every request to /swagger/doc.json — every SDK generator, every Swagger UI load, every AI coding agent told to "read our API contract" — got back 55KB starting with:

text
{
    "schemes": {{ marshal .Schemes }},

...instead of JSON. For four months. It survived because the drift test read the committed file on disk, which was valid the whole time, and nothing ever inspected what the live endpoint actually returned. Fixed in #1266, with a new test that specifically asserts the rendered document parses.

The plan for an official SDK, in order

  1. Generate, don't hand-write. openapi-generator for TypeScript and Python, regenerated in CI from the spec the drift test already guards — a hand-written client is a second contract to keep in sync with the API, and this platform has already paid once for what one drifting contract costs.
  2. A thin hand-written layer on top, for the three things a generator does badly: HMAC webhook signature verification, idempotency-key retry helpers, typed error classes matching Errors.
  3. Standard Webhooks is already on the wire — wrap it, don't reinvent it. Every delivery, and every Test-button press, carries the Standard Webhooks webhook-id / webhook-timestamp / webhook-signature headers alongside the legacy X-Webhook-* set, computed from the same delivery id and timestamp (webhook_dispatcher.go:109-114, :1195-1207; internal/webhooks/handlers.go:1343-1347). The one remaining wrinkle is the secret: it is minted as whsec_<uuid>, which is not base64, so the off-the-shelf libraries need their raw-key constructor rather than the default one (details on Webhooks). An SDK's verifier helper should encapsulate exactly that and nothing else. Nothing here blocks generation any more — an earlier revision of this page said it did.

Next

All pages