# AI agents & coding tools

> Everything an AI assistant or AI coding tool (Cursor, Lovable, Bolt, v0, Replit, ChatGPT, Claude) needs to understand and build against the Qualy API.

Qualy is built to be read and used by AI. Whether you're pointing an AI coding tool at Qualy to generate an integration, or connecting an assistant that calls the API on your behalf, everything it needs is published in a machine-readable form — a curated `llms.txt` index, plain-Markdown docs, an OpenAPI spec, a glossary, and a remote [MCP server](/docs/mcp-server.md).

This page is the one link to hand an AI tool. Paste it (or the resources below) into your assistant and it can get from zero to a working payment on its own.

---

## Two ways AI works with Qualy

There are two distinct things an AI tool might do, and they use different resources:

- **Generate integration code** — a coding tool (Cursor, Lovable, Bolt, v0, Replit, GitHub Copilot) writes an app that talks to the Qualy REST API. It needs *documentation it can read*: the `llms.txt` index, the Markdown docs, and the OpenAPI spec.
- **Call the API directly** — an assistant (ChatGPT, Claude, or your own agent) performs tasks against your live data: find a contact, raise a payment request, search. It connects to the [MCP server](/docs/mcp-server.md), which exposes a curated, tenant-scoped set of tools.

Many teams use both — a coding tool to build their product surface, an assistant for day-to-day operations.

---

## Machine-readable resources

Every resource below is public and stable. Point any tool at these URLs.

| Resource | URL | What it's for |
|----------|-----|---------------|
| **llms.txt** | [`docs.qualyhq.com/llms.txt`](https://docs.qualyhq.com/llms.txt) | Curated, section-grouped index of every doc page plus the OpenAPI spec, following the [llms.txt](https://llmstxt.org) convention. The best single entry point for a coding tool. |
| **Markdown docs** | `docs.qualyhq.com/<path>.md` | Every doc page is also served as clean Markdown — append `.md` to any docs URL (e.g. [`/docs/authentication.md`](https://docs.qualyhq.com/docs/authentication.md)). No HTML to parse. |
| **OpenAPI spec** | [`v1-spec.qualyhq.com/swagger-spec.json`](https://v1-spec.qualyhq.com/swagger-spec.json) | The full machine-readable API surface — every endpoint, request/response shape, and auth scheme. Feed it to a tool to scaffold a client. |
| **Glossary** | [`docs.qualyhq.com/glossary.json`](https://docs.qualyhq.com/glossary.json) | Machine-readable definitions of Qualy terms (payment intent, split, tenant, order…). |
| **MCP server** | [`api.qualyhq.com/v1/mcp`](/docs/mcp-server.md) | Remote MCP endpoint for assistants that call the API as tools. |
| **MCP registry entry** | [`docs.qualyhq.com/server.json`](https://docs.qualyhq.com/server.json) | Machine-readable [MCP registry](https://registry.modelcontextprotocol.io) entry — name, logo, and endpoint. |

> **Note — Ask AI**
>
> The docs site has a built-in **Ask AI** search that answers questions directly from this documentation. If you just have a question, that's often the fastest path.

---

## Point a coding tool at Qualy

The fastest way to give any AI coding tool accurate context is to hand it the `llms.txt` index. From there it can follow links to the exact pages it needs.

> Build against the Qualy API. Read https://docs.qualyhq.com/llms.txt for an index of the docs, and https://v1-spec.qualyhq.com/swagger-spec.json for the full OpenAPI spec. The base URL is https://api.qualyhq.com/v1 — it only uses GET and POST and returns JSON.

Most tools accept a docs URL or let you paste this as context. Tools with native web access (Cursor's `@Docs`, ChatGPT, Claude) can fetch the URLs directly; for others, paste the relevant `.md` pages inline.

If your tool speaks **MCP**, you can also connect the [Qualy MCP server](/docs/mcp-server.md) so the assistant can look things up against real data while it builds — Cursor, Windsurf, Replit, ChatGPT, and Claude all support remote MCP servers.

---

## The one flow that matters: accept a payment

If you tell a coding tool to "accept a payment with Qualy," this is the path to generate. Create a [Payment Intent](/docs/guides/creating-payment-intents.md) for a contact, then redirect the payer to the hosted portal URL returned in `links.short`. Qualy handles method selection, payer verification, processing, and confirmation — no payment UI to build, and card payments stay PCI-compliant on the hosted portal.

**cURL**

```bash
curl https://api.qualyhq.com/v1/payment-intents/create \
  -X POST \
  -H 'Authorization: ApiKey your-api-key-here' \
  -H 'X-TENANT-ID: your-tenant-id-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": "camila@example.com",
    "currency": "AUD",
    "items": [{ "name": "Tuition — Semester 1", "amount": 12000 }]
  }'
```

**JavaScript**

```javascript
const res = await fetch('https://api.qualyhq.com/v1/payment-intents/create', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey your-api-key-here',
    'X-TENANT-ID': 'your-tenant-id-here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact: 'camila@example.com',
    currency: 'AUD',
    items: [{ name: 'Tuition — Semester 1', amount: 12000 }],
  }),
})

const { data: intent } = await res.json()

// Send this URL to the payer — email, SMS, or a redirect.
console.log(intent.links.short)
```

The `contact` field takes an email directly thanks to [Smart references](/docs/smart-references.md) — no separate lookup needed. See [Collecting payments](/docs/guides/collecting-payments.md) for the full flow, including calling payment methods (PIX, Boleto, PayID, bank transfer) directly instead of using the portal.

---

## What a tool needs to know to get it right

A few conventions keep generated code correct on the first try:

- **Base URL** — `https://api.qualyhq.com/v1`. Only `GET` and `POST` are used; each request works on a single object (no bulk updates).
- **Auth** — two headers on every request: `Authorization: ApiKey <key>` and `X-TENANT-ID: <tenant-id>`. Create both in the [Dashboard](https://dashboard.qualyhq.com) under **Settings → API keys & webhooks**. See [API keys](/docs/api-keys.md) and [Multi-tenancy](/docs/tenants.md). (The [MCP server](/docs/mcp-server.md) uses a single bearer header and no tenant header — the tenant is encoded in the key.)
- **Responses** are wrapped in a `data` envelope — read `res.data`, not the top-level object.
- **Errors** come back with a machine-readable `code` and `message` — see [Errors](/docs/errors.md) so your tool can branch on them.
- **Idempotency** — send an [idempotency key](/docs/idempotency.md) on writes so retries never double-charge.
- **Smart references** — wherever an endpoint takes a contact, partnership, or service, you can pass a natural identifier (email, code, name) instead of an ObjectId. See [Smart references](/docs/smart-references.md).

---

## Test mode

Generated code should run against a sandbox before it touches real money. Test mode lets you simulate payments — including [test cards](/docs/testing.md) — without moving funds. Sandbox access is granted on request; [get in touch](https://qualyhq.com/contact-us/) to have it enabled for your tenant.

> **Warning — Never use real card details when testing**
>
> Use the documented [test cards](/docs/testing.md) only. Real card numbers must never be entered in test mode.