# Proquiro Public API

> Form-handler endpoints for the Proquiro marketing site. Not a general-purpose data API.
> For an HTML overview of every Proquiro developer resource (MCP server, OpenAPI spec, agent-skills index, llms.txt), see [/developers](https://proquiro.com/developers).

## Endpoints

### POST /api/demo-request

Submit a demo request. Triggers internal sales notification + 3-email buyer nurture sequence over ~14 days.

**Rate limit:** 5 requests per IP per hour
**Honeypot:** `website` field must be empty
**Rejected:** disposable email domains (mailinator, guerrillamail, etc.)

**Body:**
```json
{
  "name": "Jane Doe",
  "email": "jane@company.com",
  "company": "Acme Real Estate",
  "phone": "+91 99000 00000",
  "role": "Head of Acquisition",
  "message": "Interested in seeing the platform.",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "land-acquisition"
}
```

### GET /api/health

Service health check. Returns `{ "status": "ok", "version": "1.0.0", "timestamp": "..." }`.

## Discovery

- **OpenAPI 3.0 spec:** `/api/openapi.json`
- **API catalog:** `/.well-known/api-catalog` (RFC 9727 linkset+json)
- **Agent skills:** `/.well-known/agent-skills/index.json`
- **MCP server:** `/.well-known/mcp/server-card.json`

## Authentication

These endpoints are public form handlers — no authentication required. They are protected by:

- Per-IP rate limiting (Cloudflare D1)
- Honeypot field
- Disposable-email-domain rejection
- Server-side input validation

For the full agent authentication guide (rate limits, agent identification, partner Bearer tokens, MCP session handshake), see [`/developers/auth`](https://proquiro.com/developers/auth).

## Error schema

Every endpoint returns a structured JSON error on failure with `Content-Type: application/json`:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests from this network. Please try again later.",
    "hint": "Limit: 5 requests per IP per hour.",
    "docs": "https://proquiro.com/developers#proquiro-public-api"
  }
}
```

Stable codes: `INVALID_PAYLOAD`, `MISSING_FIELDS`, `INVALID_EMAIL`, `DISPOSABLE_EMAIL`, `HONEYPOT_TRIGGERED`, `RATE_LIMITED`, `DUPLICATE_REQUEST`, `DB_NOT_CONFIGURED`, `DB_NOT_INITIALIZED`, `INTERNAL_ERROR`. `429` responses include a `Retry-After` header.

## MCP server

The Proquiro MCP server is mounted at `POST /mcp` (Streamable HTTP, JSON-RPC 2.0). Send `Accept: application/json, text/event-stream` to negotiate SSE responses. Sessions are tracked via the `Mcp-Session-Id` response header.