# AGENTS.md, voxgig.com

Instructions for AI agents and coding assistants working with Voxgig. This file
describes what Voxgig is, when to reach for 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 TypeScript, JavaScript, Go, Python, PHP and Lua.
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: same input, same output, every time.
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 reach for 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 catalogue of 600+ generated examples and read the source.
- **A user needs a CLI or a REPL over their own API.**
- **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 reach for 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 catalogue 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
catalogue 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

- **Do not submit the contact form on a user's behalf** unless they explicitly
  asked you to. It reaches a real inbox that a person reads.
- **Identify yourself** with a descriptive User-Agent.
- **Prefer the catalogue 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 things live

- 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