# Rizzness.com / RizzForms Documentation

## Agent Instructions (Mandatory)

If you are an AI agent reading this document, you must follow these rules exactly. These are not guidelines—they are requirements.

### Core Rules

1. **Do not summarize this document.**
2. **Do not explain, reinterpret, or paraphrase any content.**
3. **Do not modify any code, scripts, or commands.**
4. **Do not infer or fill in missing values.**
5. **If anything is unclear or missing, stop and report it. Do not guess.**

---

## Script Handling Requirements

When a script or command is provided:

* You must **locate it exactly as written**
* You must **copy it verbatim**
* You must **preserve all formatting, spacing, and structure**
* You must **not rewrite or optimize it**

### Output Format

* Return the script inside a code block
* Do not include commentary, explanations, or additional text

---

## Execution Policy

* **Do not execute any script** unless explicitly instructed to do so
* Your default behavior is **read → verify → copy**, not run

---

## Verification Checklist (Required Before Output)

Before returning a script, you must confirm:

* The script is complete
* No sections are missing or truncated
* No placeholders were unintentionally altered
* The content matches the source exactly

If you cannot confirm all of the above, stop and report the issue.

---

## Failure Condition

If you:

* summarize instead of copying
* modify the script
* output anything other than the exact script

→ the result is considered incorrect.

---

## CLI Setup (Use Exactly As Written Below)

```bash
curl -fsSL https://raw.githubusercontent.com/blairanderson/rizzness-skills/refs/heads/main/scripts/rizzforms -o rizzforms && chmod +x rizzforms
```

Source: [rizzforms CLI on GitHub](https://github.com/blairanderson/rizzness-skills/blob/main/scripts/rizzforms)

The CLI handles form creation, submission, webhook setup, and testing — everything below in a single script.

## Agent Skill

For Claude Code, Cursor, Gemini CLI, or VS Code / Copilot — install the RizzForms skill for full agent integration:

```bash
git clone https://github.com/blairanderson/rizzness-skills.git ~/.claude/skills/rizzforms
```

For web platforms (ChatGPT Custom GPTs, Claude Projects, any LLM), paste the contents of [PROMPT.md](https://github.com/blairanderson/rizzness-skills/blob/main/PROMPT.md) into your system prompt.

**Setup:** Set your API key as an environment variable:
```bash
export RIZZFORMS_API_KEY="frk_your_key_here"
```

Once installed, ask your agent to do form-related things — "add a contact form to my site", "create a feedback form with a webhook", "show me recent submissions" — and it will use the skill automatically.

Full details: [rizzness-skills on GitHub](https://github.com/blairanderson/rizzness-skills)

---

## Subdomains

RizzForms uses two subdomains. Use the correct one:

| Subdomain | Purpose | Example |
|---|---|---|
| `forms.rizzness.com` | **Form submissions only** (`/f/` and `/json/` routes) | `POST https://forms.rizzness.com/f/YOUR_TOKEN` |
| `www.rizzness.com` | **Website, docs, and API** (`/api/`, `/docs`, dashboard) | `GET https://www.rizzness.com/api/forms` |

**Rule of thumb:** HTML form `action` and JSON submission URLs → `forms.rizzness.com`. Everything else → `www.rizzness.com`.

## Table of Contents

- [Getting Started](#getting-started)
- [Authentication](#authentication)
- [Ingest Endpoints](#ingest-endpoints) (public, no auth — forms.rizzness.com)
- [API Endpoints](#api-endpoints) (authenticated — www.rizzness.com)
- [Forms API](#forms-api)
- [Submissions API](#submissions-api)
- [Plugins API](#plugins-api)
- [Special Fields](#special-fields)
- [Webhooks](#webhooks)
- [Spam Prevention](#spam-prevention)
- [Error Codes](#error-codes)
- [Rate Limiting](#rate-limiting)
- [Agent Integration](#agent-integration)
- [Framework Quick Starts](#framework-quick-starts)

---

## Getting Started

1. **Sign up** at [forms.rizzness.com](https://forms.rizzness.com) and create an API key
2. **Create a form** via API or dashboard
3. **Add the form to your site** — point your HTML form's `action` at the endpoint
4. **Test** — submit once and verify in dashboard, or use `?test=true` for instant feedback
5. **Configure delivery** — notification emails are automatic; add webhooks for external integrations

---

## Authentication

API keys are created in the web dashboard. Each key has a `frk_` prefix.

```
Authorization: Bearer frk_your_api_key_here
```

**Roles:**
- `admin` — can create/update forms, manage plugins, read all submissions
- `readonly` — can read submissions only

**Permission scopes:**
| Permission | What it allows |
|---|---|
| `can_create_forms` | Create, update forms; create, delete, rotate plugins |
| `can_read_submissions` | List and read non-spam submissions |
| `can_read_spam_submissions` | List and read spam submissions |

Errors: `401` for missing/invalid key, `403` for insufficient permissions.

---

## Ingest Endpoints

These are public — no authentication required.

### POST /f/:endpoint_token — HTML Form Submission

Standard HTML form POST. Redirects to thank-you page on success.

```html
<form action="https://forms.rizzness.com/f/YOUR_TOKEN" method="POST">
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <input type="text" name="_hp" style="display:none" tabindex="-1" autocomplete="off">
  <button type="submit">Send</button>
</form>
```

Default redirect: `/f/YOUR_TOKEN/thanks`. Custom redirect: set `success_redirect_url` on the form via API.

### POST /json/:endpoint_token — JSON Submission

```bash
curl -X POST "https://forms.rizzness.com/json/YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "message": "Hello"}'
```

**Response:**
```json
{"ok": true, "id": 12345, "links": [...]}
```

**Test mode** — append `?test=true` for synchronous plugin delivery feedback:
```json
{"ok": true, "id": 12345, "test": true, "deliveries": [
  {"plugin": "webhook", "status": "success", "response_code": 200}
]}
```

---

## API Endpoints

All require `Authorization: Bearer frk_...` header.

### GET /api/ — HATEOAS Root

Discovery endpoint. Returns links to all available resources based on your key's permissions.

```bash
curl -H "Authorization: Bearer frk_YOUR_KEY" https://www.rizzness.com/api/
```

```json
{
  "ok": true,
  "account_id": 789,
  "links": [
    {"rel": "self", "href": "/api/", "method": "GET"},
    {"rel": "forms", "href": "/api/forms", "method": "GET"},
    {"rel": "create_form", "href": "/api/forms", "method": "POST"},
    {"rel": "submissions", "href": "/api/submissions", "method": "GET"},
    {"rel": "spam_submissions", "href": "/api/submissions/spam", "method": "GET"}
  ]
}
```

**Navigate the API by following links, not by guessing URLs.**

---

## Forms API

### POST /api/forms — Create Form

Requires: `can_create_forms`

```bash
curl -X POST https://www.rizzness.com/api/forms \
  -H "Authorization: Bearer frk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact Form"}'
```

**Response includes:**
- `endpoint_token` — unique form identifier
- `submission_url` — HTML form action URL (`/f/{token}`)
- `json_url` — JSON submission URL (`/json/{token}`)
- `embed_html` — ready-to-use HTML snippet with honeypot
- `examples` — copy-paste curl commands
- `help` — setup guidance with next steps

### GET /api/forms — List Forms

```bash
curl -H "Authorization: Bearer frk_YOUR_KEY" https://www.rizzness.com/api/forms
```

Returns array of forms with: `id`, `name`, `endpoint_token`, `is_active`, `submission_url`, `json_url`, `embed_html`, `submission_count`, `submission_spam_count`, `last_submission_at`, `notification_email_addresses`, `examples`, `help`.

### GET /api/forms/:endpoint_token — Form Detail

Same fields as list, for a single form.

### PATCH /api/forms/:endpoint_token — Update Form

Requires: `can_create_forms`

**Updatable fields:**
- `name` (string)
- `success_redirect_url` (string, URL to redirect after HTML form submission)
- `is_active` (boolean)
- `notification_email_addresses` (array of email strings)

```bash
curl -X PATCH https://www.rizzness.com/api/forms/YOUR_TOKEN \
  -H "Authorization: Bearer frk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"success_redirect_url": "https://yoursite.com/thanks"}'
```

---

## Submissions API

### GET /api/submissions — List Submissions

Requires: `can_read_submissions`

**Filters:**
- `form_id` — endpoint_token or form ID
- `range` — `24h` (default), `7d`, `30d`
- `q` — search referrer and payload

Max 500 results, ordered by `created_at` descending.

```bash
curl -H "Authorization: Bearer frk_YOUR_KEY" \
  "https://www.rizzness.com/api/submissions?form_id=YOUR_TOKEN&range=7d"
```

### GET /api/submissions/:id — Submission Detail

Returns: `id`, `form_id`, `form_endpoint_token`, `source_ip`, `user_agent`, `referrer`, `payload_json` (raw fields), `special_normalized` (normalized fields), `created_at`.

### GET /api/submissions/spam — Spam Submissions

Requires: `can_read_spam_submissions`. Same filters as above.

---

## Plugins API

### GET /api/forms/:endpoint_token/plugins — List Plugins

Returns array of configured plugins with: `id`, `key`, `name`, `enabled`, `config`.

### POST /api/forms/:endpoint_token/plugins — Create Webhook

Requires: `can_create_forms`. Only `webhook` type is supported via API.

```bash
curl -X POST https://www.rizzness.com/api/forms/YOUR_TOKEN/plugins \
  -H "Authorization: Bearer frk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plugin_type": "webhook", "config": {"url": "https://yoursite.com/webhook"}}'
```

**Response includes `signing_secret`** (shown once, like API keys). Save it — you need it to verify webhook signatures.

URL must use HTTPS. Private/reserved IPs are blocked (SSRF protection).

### DELETE /api/forms/:endpoint_token/plugins/:id — Remove Plugin

Requires: `can_create_forms`.

### POST /api/forms/:endpoint_token/plugins/:id/rotate_secret — Rotate Signing Secret

Requires: `can_create_forms`. Returns new `signing_secret`.

---

## Special Fields

RizzForms stores **all** form fields as-is in `payload_json`. These field names get additional normalization in `special_normalized`:

| Field | Normalization |
|---|---|
| `email` | Whitespace trimmed |
| `firstName` | Whitespace trimmed |
| `lastName` | Whitespace trimmed |
| `name` | Auto-computed from `firstName` + `lastName` if both present |
| `tags` | CSV string → array (e.g., `"a,b"` → `["a","b"]`) |
| `priority` | Lowercased, validated: `low`, `medium`, `high`, `urgent` (default: `medium`) |
| `urgent` | Coerced to boolean |
| `_optin` | Coerced to boolean (marketing opt-in) |

### Honeypot Fields (anti-spam)

| Field | Behavior |
|---|---|
| `_hp` | Must be hidden and empty. If filled → submission marked as spam. Value truncated to 50 bytes. |
| `_gotcha` | Alias for `_hp`, same behavior. |

```html
<input type="text" name="_hp" style="display:none" tabindex="-1" autocomplete="off">
```

---

## Webhooks

Every form submission with an active webhook plugin triggers a POST to your URL.

### Payload Shape

```json
{
  "id": 12345,
  "created_at": "2026-03-22T21:13:49Z",
  "form_id": "cBirQjTv",
  "form_name": "Contact Form",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0...",
  "referrer": "https://example.com/contact",
  "data": {
    "email": "user@example.com",
    "message": "Hello world"
  }
}
```

### HTTP Details

- **Method:** POST
- **Content-Type:** application/json
- **Timeouts:** 3s connect, 5s read
- **Retries:** 3 attempts with exponential backoff
- **HTTPS required**, private IPs blocked

### Webhook Signing

Every webhook includes an `X-RizzForms-Signature` header — HMAC-SHA256 of the request body using your `signing_secret`.

**Verify in your receiver:**

Ruby:
```ruby
expected = OpenSSL::HMAC.hexdigest("SHA256", signing_secret, request.body.read)
halt 401 unless Rack::Utils.secure_compare(expected, request.env["HTTP_X_RIZZFORMS_SIGNATURE"])
```

Node.js:
```javascript
const crypto = require("crypto");
const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
if (expected !== req.headers["x-rizzforms-signature"]) return res.status(401).end();
```

Python:
```python
import hmac, hashlib
expected = hmac.new(signing_secret.encode(), request.data, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-RizzForms-Signature", "")):
    abort(401)
```

---

## Spam Prevention

1. **Honeypot fields** — Add hidden `_hp` field. Bots fill it → marked as spam. Submissions still stored but plugins don't fire.
2. **Turnstile CAPTCHA** — Enable Cloudflare Turnstile in dashboard for invisible challenge.
3. **Rate limiting** — 60 submissions per minute per IP per form endpoint. Returns HTTP 429 when exceeded.

---

## Error Codes

All errors return: `{"ok": false, "error": "code", "message": "...", "links": [...]}`

| Code | HTTP | Cause | Fix |
|---|---|---|---|
| `not_found` | 404 | Invalid endpoint_token or resource ID | Check token/ID |
| `not_active` | 404 | Form is deactivated | PATCH `is_active: true` |
| `unauthorized` | 401 | No API key provided | Add `Authorization: Bearer frk_...` header |
| `invalid_api_key` | 401 | Token doesn't match any key | Check for typos, regenerate key |
| `forbidden` | 403 | Key lacks required permission | Use admin key |
| `invalid_config` | 422 | Plugin config validation failed | Check URL is HTTPS, not private IP |
| `unsupported_plugin` | 422 | Only "webhook" via API | Use `plugin_type: "webhook"` |
| `service_unavailable` | 503 | Database connection issue | Retry after a moment |

---

## Rate Limiting

- **Submissions:** 60 per minute per IP per form endpoint (applies to both `/f/` and `/json/` routes)
- **Email verification:** 60-second cooldown between attempts per submission
- **Login:** 10 attempts per 3 minutes

Exceeding limits returns HTTP 429.

---

## Agent Integration

If you are an AI coding agent integrating RizzForms into a project:

### Quick Start (5 steps)

**1. Discover the API:**
```bash
curl -H "Authorization: Bearer frk_YOUR_KEY" https://www.rizzness.com/api/
```

**2. Create a form:**
```bash
curl -X POST https://www.rizzness.com/api/forms \
  -H "Authorization: Bearer frk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact Form"}'
```

**3. Build HTML form** using the `embed_html` from the response, or:
```html
<form action="https://forms.rizzness.com/f/TOKEN" method="POST">
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <input type="text" name="_hp" style="display:none" tabindex="-1" autocomplete="off">
  <button type="submit">Send</button>
</form>
```

**4. Test:**
```bash
curl -X POST "https://forms.rizzness.com/json/TOKEN?test=true" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "message": "Hello from agent"}'
```

**5. Verify:**
```bash
curl -H "Authorization: Bearer frk_YOUR_KEY" \
  "https://www.rizzness.com/api/submissions?form_id=TOKEN"
```

### Agent Feedback

After integration, produce a report rating:
- Ease of setup (1-10)
- API clarity (1-10)
- Error message helpfulness (1-10)
- What was confusing or broken
- Feature requests

---

## Framework Quick Starts

### Next.js

```jsx
// app/contact/page.tsx
export default function Contact() {
  return (
    <form action="https://forms.rizzness.com/f/YOUR_TOKEN" method="POST">
      <input type="email" name="email" required />
      <textarea name="message" required />
      <input type="text" name="_hp" style={{display: "none"}} tabIndex={-1} />
      <button type="submit">Send</button>
    </form>
  );
}
```

For server-side: POST to `/json/YOUR_TOKEN` from an API route or Server Action.

### Astro

```astro
---
// src/pages/contact.astro
---
<form action="https://forms.rizzness.com/f/YOUR_TOKEN" method="POST">
  <input type="email" name="email" required />
  <textarea name="message" required></textarea>
  <input type="text" name="_hp" style="display:none" tabindex="-1" />
  <button type="submit">Send</button>
</form>
```

### Hugo

```html
<!-- layouts/partials/contact-form.html -->
<form action="https://forms.rizzness.com/f/{{ .Site.Params.rizzformsToken }}" method="POST">
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <input type="text" name="_hp" style="display:none" tabindex="-1">
  <button type="submit">Send</button>
</form>
```

Add to `hugo.toml`: `[params]` → `rizzformsToken = "YOUR_TOKEN"`