# SDKs and OpenAPI

The API is plain JSON over HTTPS, so any HTTP client works. These make it shorter.

The clients are open source under the MIT license in [Keyveve/veqen-sdks](https://github.com/Keyveve/veqen-sdks). That repository also includes an attributed, daily-refreshed mirror of the public CC0 disposable-email blocklist.

## Python

```bash
pip install veqen==0.1.0
```

```python
from veqen import Veqen

client = Veqen()  # reads VEQEN_API_KEY from the environment
result = client.signup(email="jane@mailinator.com", ip="185.220.101.1")
if result["risk"]["verdict"] == "refuse":
    print([r["message"] for r in result["risk"]["reasons"]])
```

Methods: `email(address, verify_mailbox=False)`, `emails(list)`, `ip(address)`, `phone(number, country=None)`, `domain(name)`, `signup(email=, ip=, phone=, phone_country=)`, `account()`, `usage(days=30)`. Errors raise `VeqenError` with `.type`, `.status` and `.message`. Retries on 429 and 5xx are built in.

## JavaScript / TypeScript

```bash
npm install https://veqen-app.com/static/sdk/veqen-sdk-0.1.0.tgz
```

```javascript
import { Veqen } from "@veqen/sdk";

const veqen = new Veqen(); // reads VEQEN_API_KEY
const result = await veqen.signup({ email: "jane@mailinator.com", ip: "185.220.101.1" });
console.log(result.risk.verdict);
```

Works in Node 20+ and server runtimes with `fetch` and `crypto.randomUUID`. Full TypeScript types included. Keep your API key on your server, never in browser code.

The downloads above are hosted by Veqen; registry publication on PyPI and npm is pending. Each SDK generates an idempotency key for a check and reuses it for retries, preventing duplicate credit charges. This means check responses are retained for up to 24 hours as described in the [idempotency docs](/docs/idempotency).

## OpenAPI

The machine-readable spec is at [`https://veqen-app.com/openapi.json`](https://veqen-app.com/openapi.json) (OpenAPI 3.1). Import it into Postman, Insomnia, or a code generator.

## Docs for AI assistants

- [`/llms.txt`](https://veqen-app.com/llms.txt): a short index of these docs for language models.
- [`/llms-full.txt`](https://veqen-app.com/llms-full.txt): every docs page in one Markdown file. Paste it into your coding assistant's context.
- Add `.md` to any docs URL to get it as Markdown, for example [`/docs/signup-check.md`](/docs/signup-check.md).