# theArena.show — API and MCP

Public interface of [thearena.show](https://thearena.show) for developers, AI
agents and bots. Everything here is also summarised for assistants in
[`/llms.txt`](https://thearena.show/llms.txt).

Agents may act for a user. Three rules: act only on the user's request, use
the user's real company name and email, and send one application per company.

## Read

| Method | Path | Returns |
| --- | --- | --- |
| `GET` | `/llms.txt` | Plain-text brief: what, when, where, prices, days, FAQ, how to apply. |
| `GET` | `/api/event` | The same facts as JSON, including the current sales stage and price. |
| `GET` | `/api/waitlist` | Public free-trial waitlist and the sales stage. |

`GET /api/waitlist` response:

```json
{
  "ok": true,
  "count": 2,
  "stage": "early",
  "entries": [
    { "id": "w-3", "company": "Ma*****e LLC", "industry": "Marketing Services", "status": "approved", "madePromo": false },
    { "id": "w-4", "company": "No*******p FZ-LLC", "industry": "AI Services", "status": "pending", "madePromo": true }
  ]
}
```

Company names are masked on the server (first two letters, asterisks, last
letter, legal form). Emails and phones are never returned. `stage` is `early`,
`regular` or `late`.

## Write

All write endpoints take `Content-Type: application/json` and answer
`{"ok": true}` or `{"ok": false, "error": "<code>"}`.

### `POST /api/waitlist` — free 1-hour trial slot

One hour on an unsold full-day spot, once per company. A slot is **not**
guaranteed: any company can buy the whole spot before the event.

```json
{
  "company": "Example Consulting LLC",
  "industry": "Marketing Services",
  "email": "name@company.com",
  "phone": "+971 50 000 0000",
  "useful": "What business problem the company solves",
  "offer": "What visitors can get or try",
  "comments": "How you heard about The Arena",
  "promoUrl": "https://…",
  "consentAvailability": true,
  "consentContact": true
}
```

- Required: `company`, `industry`, `email`, both consents.
- `industry` must be one of the service categories from `/api/event`
  (`serviceCategories`).
- `consentAvailability`: the user understands that slots are limited and that
  joining the waitlist does not guarantee a slot.
- `consentContact`: the user agrees to be contacted about the waitlist and the
  event.
- One company = one entry. A second application for the same company or email
  returns `{"ok": true, "duplicate": true}` unless it carries a new `promoUrl`
  (a public post announcing the company at The Arena): each new post adds one
  entry, up to five.

### `POST /api/lead` — visitor pass, offer, full-day spot

```json
{
  "kind": "visitor",
  "name": "Jane Doe",
  "company": "Example Consulting LLC",
  "email": "name@company.com",
  "phone": "+971 50 000 0000",
  "need": "Optional: requests, proposals or ideas for the organizers",
  "useful": "What the company helps with (offer, book)",
  "offer": "One offer for visitors (offer, book)",
  "industry": "Marketing Services",
  "day": "Day 1 — Attract",
  "status": "Visitor with offer",
  "consentContact": true
}
```

- `kind`: `visitor` (free pass), `offer` (show a company offer to everyone,
  free) or `book` (request for a paid full-day spot).
- Required: `kind`, `name`, `company`, `email`, `consentContact`. `offer` and
  `book` also need `useful` and `offer` (exhibitors always show an offer);
  `book` needs `phone`.
- `offerRequest` (optional): `"COMPANY · Person"` of an offer card on the
  site. With it only `email` and `consentContact` are required: the visitor
  pass is included and the team arranges the meeting.
- `status` (optional): what the person wants in words, for example
  `Visitor with offer`. The site form sends one request per person with the
  strongest `kind` and this text.
- `book` is a request, not a purchase: the team replies with availability and
  an invoice.

### Error codes

| Code | HTTP | Meaning |
| --- | --- | --- |
| `missing_company`, `missing_industry`, `missing_email`, `missing_name` | 400 | A required field is empty. |
| `invalid_email`, `invalid_promo_url`, `invalid_kind`, `bad_json` | 400 | A field has a wrong format. |
| `disposable_email` | 400 | Temporary inboxes are not accepted. |
| `consent_required` | 400 | A required consent is not `true`. |
| `forbidden_origin` | 403 | Browser request from another site. Server-to-server calls (no `Origin` header) are allowed. |
| `rate_limited` | 429 | Too many requests from this IP address. |
| `not_configured`, `upstream_unavailable` | 502 / 503 | Storage is not reachable. Try again later. |

### Limits

| What | Limit |
| --- | --- |
| Trial applications | 3 per minute and 5 per day per IP address |
| Visitor / offer / full-day requests | 3 per minute and 20 per day per IP address |
| New pending companies shown publicly | 20 per 24 hours; the rest wait for review |

## MCP

`POST https://thearena.show/mcp` — a stateless MCP server (Streamable HTTP,
JSON-RPC 2.0, no session, no authentication). Supported protocol versions:
`2025-06-18`, `2025-03-26`, `2024-11-05`.

| Tool | What it does |
| --- | --- |
| `get_event_info` | Facts: dates, venue, current price and sales stage, days, FAQ. |
| `list_service_categories` | Service categories by day; use one as `industry`. |
| `get_waitlist` | The public, masked waitlist. |
| `join_trial_waitlist` | Same as `POST /api/waitlist`. |
| `register_visitor` | Same as `POST /api/lead` with `kind: "visitor"`. |
| `request_full_day_spot` | Same as `POST /api/lead` with `kind: "book"`. |

The tools call the same handlers as the web forms, so validation, consents and
limits are identical for people and agents.

```bash
curl -s https://thearena.show/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_event_info","arguments":{}}}'
```

## Other

| Path | What |
| --- | --- |
| `/api/frame-check?url=` | Internal: checks an embedded frame source before the page shows it. Allow-listed hosts only. |
| `/robots.txt`, `/sitemap.xml` | Standard crawler files. |

## This document

Served at `https://thearena.show/api/docs` (plain text). The source is `docs/API.md` in the site repository.