# Trial Portal - Full API Documentation

## Overview

The Trial Portal generates 30-day trial license keys for OptimaJet Workflow Engine.
It validates the email, generates a license key, and sends it via email.

Base URL: `https://trial.workflowengine.io`

---

## Endpoints

### POST /api/trial/llm

Programmatic endpoint for LLM agents. Returns a minimal response with only `success`, `message`, and `licenseKey`.

**Request:**
```json
{
  "email": "user@company.com",
  "companyName": "Company Name"
}
```

**Success response (200):**
```json
{
  "success": true,
  "message": "Check your email. We've sent the trial license key and setup instructions.",
  "licenseKey": "V2-TRIAL_Company_Name-..."
}
```

**Error response (400/429):**
```json
{
  "success": false,
  "message": "Please use a business email address."
}
```

## Request validation

| Field | Required | Validation |
|-------|----------|------------|
| `email` | Yes | Valid email format, business domain (no gmail.com, yahoo.com, mailinator.com, etc.), trimmed, case-normalized |
| `companyName` | Yes | Non-empty |

## Rate limits

| Limit | Scope | Value |
|-------|-------|-------|
| Cooldown | per email | 1 request per 24 hours |
| Lifetime | per email | 3 keys max |
| Global | all | Unlimited |

## Error codes

| HTTP | StatusCode | Meaning |
|------|------------|---------|
| 400 | null | Invalid email (format, domain, or disposable) |
| 400 | null | Empty company name |
| 400 | null | Key generation failed |
| 400 | null | Email sending failed (key not sent) |
| 429 | 429 | Rate limit (24h cooldown or lifetime limit reached) |