# AGENTS.md — subba.pro

subba is an AI receptionist for small businesses. It answers a business's website
contact form and lets customers book appointments, classes, and jobs. This file
tells AI agents how to discover and use subba on a business's behalf.

- Product: https://subba.pro
- Docs: https://subba.pro/docs
- API base: https://api.subba.pro
- Operated by: Polarize Ltd. All communications are by email: hello@subba.pro

## What an agent can do today (stable REST, JSON)

Each business has a public booking slug. Replace `{slug}` and `{formId}` accordingly.

### 1. Submit an enquiry to a business's form
`POST https://api.subba.pro/f/{formId}`
Body (JSON): `{ "name": string, "email": string, "message": string }`
Returns: `{ "ok": true, "status": "processed" }`
The request must be sent from the form's registered origin. subba filters spam,
replies in the business's voice, and books a meeting when the enquiry asks for one.

### 2. List a business's bookable services
`GET https://api.subba.pro/api/b/{slug}/services`
Returns: `{ "business": string, "services": [ { "id", "name", "type", "duration", "price", "currency", "requiresPayment" } ] }`
`type` is one of `appointment`, `class`, `job`. `price` is in minor units (pence).

### 3. Get availability for a service
`GET https://api.subba.pro/api/b/{slug}/slots?service={serviceId}&date=YYYY-MM-DD`
Returns (appointments/jobs): `{ "type", "slots": [ { "start": epochMs, "resourceId" } ] }`
Returns (classes): `{ "type": "class", "sessions": [ { "id", "start": epochMs, "left": number } ] }`

### 4. Create a booking
`POST https://api.subba.pro/api/b/{slug}/book`
Body (JSON): `{ "service": serviceId, "start": epochMs (or "session": sessionId for classes), "name": string, "email": string }`
Returns: `{ "ok": true, "bookingId": string, "checkoutUrl": string|null, "confirmed": boolean }`
If the service requires payment, follow `checkoutUrl` (Stripe) to pay; the payment
settles to the business's own connected Stripe account.

## MCP server (Streamable HTTP)

An MCP endpoint is available at `https://api.subba.pro/mcp` (JSON-RPC 2.0, stateless).
Add it to any MCP-capable client. Tools:
- `list_services` (args: `slug`)
- `check_availability` (args: `slug`, `service`, optional `date`)
- `create_booking` (args: `slug`, `service`, `start` or `sessionId`, `name`, `email`)

`GET https://api.subba.pro/mcp` returns server info and the tool list. The same MCP
server is a **ChatGPT app** (Apps SDK): `create_booking` declares an inline widget
(`ui://widget/subba-booking.html`, served via `resources/list` + `resources/read`)
that shows a confirmation or a secure-payment button.

## Discovery feed (ACP) and per-business manifests

- **ACP product feed** (each bookable service as a product, OpenAI/Agentic Commerce
  Protocol JSONL schema): `https://api.subba.pro/acp/feed.jsonl` (all businesses) or
  `https://api.subba.pro/b/{slug}/acp/feed.jsonl` (one business).
- **Per-business ai2w manifest**: `https://api.subba.pro/b/{slug}/ai2w`, also served on
  each business's own website at `/ai2w`.

## Guidelines for agents

- Always confirm the exact service, time, price, and business with the human before
  calling `create_booking` or `/book`. A booking is a real commitment for a real business.
- Never submit a form or booking with data the human did not provide.
- Rate limits apply per form and per IP. Back off on `429`.

## Roadmap (not yet available)

ACP is supported for **discovery** (the product feed above) and subba ships a ChatGPT
app built on the MCP server. **Native in-chat payment** (ACP shared payment token,
Agent Payments Protocol / AP2) is not yet enabled: today, payment completes on the
Stripe Checkout link that `create_booking` returns. In-chat settlement needs Stripe's
agentic commerce enabled on the platform account and will be added then.

- Machine manifest: https://subba.pro/ai2w (per business: https://api.subba.pro/b/{slug}/ai2w)
- ACP product feed: https://api.subba.pro/acp/feed.jsonl
- Agent card: https://subba.pro/.well-known/agent.json
- LLM sitemap: https://subba.pro/llms.txt (full: https://subba.pro/llms-full.txt)