# API Documentation

Integrate waitlists into your application with our simple REST API

## Quick Start

Get started with Omelette API in 3 simple steps:

1. Create a waitlist in your [dashboard](https://omelette.net/app)
2. Get your API key and waitlist ID
3. Start making API requests to the endpoints below

## Authentication

All API requests require authentication using your API key. You can authenticate in two ways:

### Method 1: API Key Header (Recommended)

Include your API key in the request headers:

```
X-Waitlist-Api-Key: your_api_key_here
```

### Method 2: Domain Whitelist

For client-side JavaScript, add your domain to the allowed domains list in your waitlist settings.

## Base URL

`https://omelette.net/api`

## API Endpoints

### Create Subscriber

Add a new subscriber to your waitlist

POST`/api/subscribers/create`

#### Request Body

```
{
  "waitlist": "your_waitlist_id",
  "email": "user@example.com",
  "name": "John Doe",           // Optional
  "phone": "+1234567890",       // Optional
  "referredBy": "abc123",       // Optional: referral code
  "metadata": {                 // Optional: Pro plan only
    "source": "landing_page",
    "userId": "user_123"
  }
}
```

#### Example Request

```
curl -X POST https://omelette.net/api/subscribers/create \
  -H "Content-Type: application/json" \
  -H "X-Waitlist-Api-Key: your_api_key" \
  -d '{
    "waitlist": "your_waitlist_id",
    "email": "user@example.com",
    "name": "John Doe"
  }'
```

#### Response

```
{
  "message": "Subscriber created",
  "subscriber": {
    "id": "clm1234567890",
    "email": "user@example.com",
    "name": "John Doe",
    "referralCode": "abc123",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}
```

### Retrieve Subscriber

Get subscriber information and waitlist position

POST`/api/subscribers/retrieve`

#### Request Body

```
{
  "waitlist": "your_waitlist_id",
  "email": "user@example.com"
}
```

#### Example Request

```
curl -X POST https://omelette.net/api/subscribers/retrieve \
  -H "Content-Type: application/json" \
  -H "X-Waitlist-Api-Key: your_api_key" \
  -d '{
    "waitlist": "your_waitlist_id",
    "email": "user@example.com"
  }'
```

#### Response

```
{
  "message": "Subscriber retrieved",
  "subscriber": {
    "id": "clm1234567890",
    "email": "user@example.com",
    "name": "John Doe",
    "referralCode": "abc123",
    "referralCount": 3,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}
```

### Delete Subscriber

Remove a subscriber from your waitlist

POST`/api/subscribers/delete`

#### Request Body

```
{
  "waitlist": "your_waitlist_id",
  "email": "user@example.com"
}
```

#### Example Request

```
curl -X POST https://omelette.net/api/subscribers/delete \
  -H "Content-Type: application/json" \
  -H "X-Waitlist-Api-Key: your_api_key" \
  -d '{
    "waitlist": "your_waitlist_id",
    "email": "user@example.com"
  }'
```

#### Response

```
{
  "message": "Subscriber deleted"
}
```

## Error Handling

All API responses use standard HTTP status codes. Errors return JSON with a descriptive message:

### 400 Bad Request

```
{
  "message": "Email is required"
}
```

### 403 Forbidden

```
{
  "message": "This feature requires a Pro subscription. Please upgrade to continue."
}
```

### 404 Not Found

```
{
  "message": "Waitlist not found"
}
```

## SDKs & Libraries

While our API is simple enough to use with standard HTTP requests, here are some popular libraries for different platforms:

### JavaScript/TypeScript

```javascript
// Using fetch (built-in)
fetch('https://omelette.net/api/subscribers/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Waitlist-Api-Key': 'your_key'
  },
  body: JSON.stringify({
    waitlist: 'your_waitlist_id',
    email: 'user@example.com'
  })
})
```

### Python

```python
import requests

response = requests.post(
  'https://omelette.net/api/subscribers/create',
  json={
    'waitlist': 'your_waitlist_id',
    'email': 'user@example.com'
  },
  headers={
    'X-Waitlist-Api-Key': 'your_key'
  }
)
```

## Need Help?

Check out our integration examples in your dashboard or contact support