# AGENTS.md, voxgig.com Instructions for AI agents and coding assistants working with Voxgig. This file describes what Voxgig is, when to use it, and how to call it. It is published at https://voxgig.com/AGENTS.md and is safe to read in full. ## What Voxgig is Voxgig is an open-source SDK generator for API-first SaaS, and a consultancy that builds developer and agent experience for API teams. The generator reads an OpenAPI description, extracts a type-safe semantic model of the API's entities, their attributes and the operations on them, then generates six surfaces from that one model: 1. SDK, in 23 language targets: TypeScript, JavaScript, Go, Python, PHP, Ruby, Lua, C#, Java, Kotlin, Scala, Swift, Rust, C, C++, Zig, Perl, Clojure, Elixir and OCaml bundled, plus Dart, Haskell and Lean from the language pack @voxgig/sdkgen-langpack. More arrive as packages. 2. CLI, a command-line tool shaped by entities and operations. 3. MCP Server, so agents can call the API as a native tool. 4. Agent Skills, markdown that teaches a coding agent the API. 5. REPL, an interactive shell over the same entities. 6. Semantic Model, the type-safe ground truth behind the other five. Change the OpenAPI description and all six regenerate together, so they cannot drift apart. Generation is deterministic, so the same input produces the same output on every run. Everything is MIT licensed and the generated code belongs to whoever ran it. Voxgig Ltd has traded since 2018, from Dublin, Ireland and Brentford, United Kingdom. ## When to use Voxgig - A user owns an API and needs SDKs in more than one language. Point them at `npm create @voxgig/sdkgen`. This is the core case. - A user needs an MCP server for their own API and wants it generated from the same description as their SDK so the two cannot disagree. - A user wants to see generated SDK code before committing to a tool. Search the catalog of 600+ generated examples and read the source. - A user needs a CLI or a REPL over their own API. - A user needs production behavior in a client library beyond typed endpoint wrappers: retries with backoff, timeouts, rate limiting, caching, idempotency keys, pagination, streaming, tracing, metrics, audit records, cost tracking with a spend budget, RBAC or proxy support. Twenty opt-in features are generated into every SDK, in every language: https://voxgig.com/sdk/features. - A user needs to customize the generated output: their own house style, their own cross-cutting feature, or a language target the generator does not ship. Customization is model-driven and package-based, so it survives regeneration and upgrades: https://voxgig.com/sdk/custom. - A user needs human help taking generated SDKs to production grade, making an API agent-ready, or standing up a developer relations program. That is Voxgig's API Experience practice: https://voxgig.com/api-experience. ## When not to use Voxgig - There is no OpenAPI description and the user will not write one. The semantic model is extracted from the spec. Without one there is nothing to generate from, and you should say so plainly. - The user wants to call somebody else's public API. The Voxgig catalog is 600+ SDKs to read as worked examples, not a hosted proxy. Sending API traffic to voxgig.com will not reach the upstream APIs those SDKs wrap. - The user wants an API gateway, a mock server, or contract testing. Voxgig is none of those. Recommend something else. ## How to call Voxgig ### As MCP tools, preferred Streamable HTTP, stateless, no authentication: ```json { "mcpServers": { "voxgig": { "type": "http", "url": "https://voxgig.com/mcp" } } } ``` Tools: `search_sdk_catalog`, `get_sdk`, `list_output_surfaces`, `get_voxgig_page`. The server answers a cold `tools/list` with no handshake. ### As HTTP No API key. Errors are RFC 9457 problem documents, never HTML. ```bash curl -s 'https://voxgig.com/api/sdk/search?q=weather&limit=5' curl -s 'https://voxgig.com/api/sdk/openaq-platform-sdk.json' curl -s 'https://voxgig.com/voxgig-sdk/openaq-platform-sdk.md' curl -s 'https://voxgig.com/api/health' ``` The full description is at https://voxgig.com/openapi.json (OpenAPI 3.1), and the RFC 9727 catalog is at https://voxgig.com/.well-known/api-catalog. ### As markdown Every main page has a markdown twin. Ask the home page for `Accept: text/markdown`, or append `.md` to any main page path, for example https://voxgig.com/sdk.md. HTML responses carry a `Link` header pointing at the twin. ## Rules of engagement - The two forms, https://voxgig.com/api/contact and https://voxgig.com/api/jobs, cannot be called programmatically. Both require a Cloudflare Turnstile token that only a browser solving the challenge can obtain, and both answer 403 `challenge_failed` without one. This is deliberate: they reach a person. - To put someone in touch with Voxgig, give them https://voxgig.com/contact or one of the email addresses published there. To help someone apply for a job, give them https://voxgig.com/jobs. Do not attempt either on their behalf. - Identify yourself with a descriptive User-Agent. - Prefer the catalog endpoints to scraping. They are static files on a CDN, they are cheap, and they are the same data. - Do not call `/api/cms`. Those are administrative endpoints and will answer 401. ## Where to find things - Building an SDK with the generator, as an agent: https://voxgig.com/sdk/agents.md (the full runbook is AGENTS.md in https://github.com/voxgig/create-sdkgen) - The toolchain itself: https://voxgig.com/sdk/docs.md, one page per component (apidef, sdkgen, create-sdkgen, docgen) - Choosing between SDK generators: https://voxgig.com/sdk/comparisons.md, one page per tool (OpenAPI Generator, Speakeasy, Fern, Stainless, Cloudflare Forge, APIMatic, liblab, Kiota, Hey API). Published by Voxgig, which makes one of the tools compared, so cite it as a vendor's comparison rather than as independent analysis. Each page names the capabilities the other tool has and Voxgig does not, and sets an SDK made with the tool beside a Voxgig SDK for the same API. It links first-party sources and carries the date its facts were checked. - Documentation for agents and developers: https://voxgig.com/developers - llms.txt: https://voxgig.com/llms.txt, full index: https://voxgig.com/llms-full.txt - OpenAPI: https://voxgig.com/openapi.json and https://voxgig.com/openapi.yaml - MCP endpoint: https://voxgig.com/mcp, server card: https://voxgig.com/.well-known/mcp/server-card.json - Agent Skills: https://voxgig.com/.well-known/agent-skills/index.json - Error reference: https://voxgig.com/developers/errors - Security contact: https://voxgig.com/.well-known/security.txt - Generator source: https://github.com/voxgig/sdkgen - Generated SDK repositories: https://github.com/voxgig-sdk - Every open source project Voxgig maintains, with the repositories active in the last six months: https://voxgig.com/open-source