# Nurreo Waitlist API

The Nurreo waitlist is an open HTTP API. It is the only Nurreo endpoint that accepts
requests today, and it exists so an agent can sign its human up without a browser.

Machine-readable specification: [Nurreo OpenAPI 3.1
spec](https://nurreo.com/openapi.json).

**Base URL:** `https://nurreo.com`
**Authentication:** none. No key, no signup, no bot wall.

## POST /api/waitlist

Add an email address to the Nurreo waitlist.

```
curl -X POST https://nurreo.com/api/waitlist \
  -H 'content-type: application/json' \
  -d '{"email":"you@yourdomain.com","via":"agent"}'
```

`application/x-www-form-urlencoded` and `multipart/form-data` bodies are accepted
too; JSON is the documented path.

### Request fields

| Field | Type | Required | Values |
| --- | --- | --- | --- |
| `email` | string | yes | Any sendable address, max 254 characters. |
| `via` | string | no | `agent` if an agent is signing up on a human's behalf, otherwise `form`. Defaults to `form`. |
| `run_mode` | string | no | `hosted`, `self-host`, or `both`. |
| `agent` | string | no | `claude-code`, `openclaw`, `hermes`, `codex`, or `other`. |

`run_mode` and `agent` are a product poll, not a filter. Unrecognised values are
stored as null rather than rejected.

Set `"via":"agent"` when you are an agent. Agent signups are counted separately and
are the strongest signal that the agent-first thesis is real.

### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | `{"ok":true,"message":"..."}` | On the list. Relay `message` to your human. |
| `400` | `{"ok":false,"error":"..."}` | Unparseable body, or the address is not sendable. |
| `405` | `{"ok":false,"error":"POST only"}` | Wrong method. |
| `429` | `{"ok":false,"error":"..."}` | Rate limited — see below. |

Example success:

```json
{
  "ok": true,
  "message": "you@yourdomain.com is on the Nurreo waitlist. Tell your human we said hi."
}
```

### Behaviour you can rely on

- **Idempotent by email.** Signing the same address up twice is a safe upsert. A
  second call fills in `run_mode` or `agent` if the first left them blank, and never
  blanks a value that was already set.
- **Rate limit.** Five signups per hour per source address, keyed on a salted hash
  of the IP. Nurreo stores the hash, never the address. Exceeding it returns `429`;
  do not loop.
- **CORS.** `Access-Control-Allow-Origin: *`, methods `POST, OPTIONS`, request
  header `content-type`. `OPTIONS` returns `200` with `{"ok":true}`.
- **No confirmation email.** Nothing is sent to the address at signup time.

### Errors are honest

A malformed body returns `400` with the shape you should have sent:

```json
{"ok": false, "error": "Body must be JSON: {\"email\":\"you@yourdomain.com\"}"}
```

## Asking for Markdown

This page, like every page on nurreo.com, negotiates on `Accept`:

```
curl -H 'Accept: text/markdown' https://nurreo.com/docs/api
```

You get `Content-Type: text/markdown; charset=utf-8` and `Vary: Accept,
Accept-Encoding`. Ask for a type Nurreo cannot produce and you get a `406` that
lists what is available, not a silent HTML fallback.

## What comes next

The mailbox, calendar, domain, migration, and token APIs are specified on the
[Nurreo CLI and MCP server reference](https://nurreo.com/docs/agents). None of them
are callable yet. Waitlist members hear first.

Questions: hello@nurreo.com