§03 · OpenAPI 3.1

The contract, served as a static asset.

Every public-API endpoint, request shape, response shape and error code is described in a single OpenAPI 3.1 document. Hosted at a versioned URL, far-future cache, CORS-open. If you can read YAML you can integrate.

Where it lives

URL
https://www.vaanilabs.in/openapi/v1/vaanivoice.yaml

Versioned in the path (/openapi/v1/...); the spec itself carries info.version: "1.0.0". Breaking schema changes will land at /openapi/v2/... — the v1 URL stays pinned and immutable.

Cache headers: public, max-age=3600, s-maxage=86400, must-revalidate. CORS is wide open (Access-Control-Allow-Origin: *) so agentic frameworks can fetch it from anywhere.

Sanity check

Terminalbash
curl -sS https://www.vaanilabs.in/openapi/v1/vaanivoice.yaml | head -40

Validate it locally with the Redocly CLI:

Validatebash
npx -y @redocly/cli lint https://www.vaanilabs.in/openapi/v1/vaanivoice.yaml

Preview as docs

Terminalbash
npx -y @redocly/cli preview-docs https://www.vaanilabs.in/openapi/v1/vaanivoice.yaml

Opens a Redoc-style page at http://localhost:8080 with every endpoint expanded.

Wire it into LangChain (Python)

Pythonpython
from langchain_community.agent_toolkits.openapi.toolkit import OpenAPIToolkit
from langchain_community.utilities.requests import RequestsWrapper
from langchain_openai import ChatOpenAI
import yaml, requests

spec = yaml.safe_load(requests.get(
  "https://www.vaanilabs.in/openapi/v1/vaanivoice.yaml"
).text)

toolkit = OpenAPIToolkit.from_llm(
    llm=ChatOpenAI(model="gpt-4o-mini"),
    json_spec=spec,
    requests_wrapper=RequestsWrapper(headers={
        "Authorization": "Bearer vv_live_REPLACE_ME"
    }),
    allow_dangerous_requests=True,
)

agent = toolkit.create_agent()
agent.invoke({"input": "Create a plain meeting room titled 'OpenAPI smoke test'."})

The agent now has typed tools for every endpoint. Errors come back in the standard { "error": "..." } envelope; the agent learns the codes from the responses blocks in the spec.

Generate a client (Stainless / Speakeasy / Fern)

Terminalbash
# Stainless / Speakeasy / Fern — point at the spec URL:
stainless build --spec https://www.vaanilabs.in/openapi/v1/vaanivoice.yaml --target typescript-node

Substitute your generator of choice. Because the spec is OpenAPI 3.1 (not 3.0), generators that only parse 3.0 may need a downgrade step — most modern ones (Stainless, Speakeasy, Fern, openapi-ts) handle 3.1 natively.

Cursor agent tools

Cursor lets you register an OpenAPI URL as a tool source: Settings → Tools → Add OpenAPI. Paste the spec URL above, add the Authorization: Bearer vv_live_… header, and Cursor exposes every endpoint to the agent automatically.

What’s in the spec

  • 4 public endpoints — textvoice, voicebot, meeting-agent, meeting — under /api/public/v1/*, secured by bearerAuth (vv_live_…).
  • 5 dashboard endpoints — list / create / revoke keys, get usage rollup — secured by cookieAuth (Supabase session). Documented for completeness; not callable with an API key.
  • Components for every request and response shape, plus reusable error envelopes (Unauthorized, InsufficientBalance, Forbidden, RateLimited, BackendError).
  • Examples on every request and response so generators emit useful default fixtures.