---
title: "PAI Palooza API Reference"
description: "Complete API reference for the PAI Palooza AI hackathon and event advertising platform"
canonical: "https://docs.ainative.studio/docs/community/pai-palooza-api"
last-updated: "2026-10-19T22:48:47.150Z"
---

# PAI Palooza API Reference

Source: https://docs.ainative.studio/docs/community/pai-palooza-api

> Complete API reference for the PAI Palooza AI hackathon and event advertising platform

# PAI Palooza API Reference

PAI Palooza is an AI hackathon and event advertising platform built into AINative Studio. It connects event organizers with sponsors through a programmatic ad marketplace, complete with dynamic pricing, real-time tracking, revenue sharing, and Stripe-powered payouts.

**Base URL:** `https://api.ainative.studio/api/v1/paipalooza`

## Authentication

Most endpoints require a Bearer token. Include it in the `Authorization` header:

```
Authorization: Bearer <your-token>
```

Public endpoints (ad serving, tracking, pricing estimates, inventory browsing) do not require authentication and are marked accordingly.

---

## Events

Manage AI events with semantic embedding generation for ad targeting.

**Base path:** `/api/v1/paipalooza/events`

### POST / -- Create Event

Create a new AI event. Generates semantic embeddings for ad targeting.

**Auth:** Bearer token required (organizer)

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/events/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Builder Hackathon 2026",
    "event_type": "hackathon",
    "description": "48-hour AI hackathon focused on agent development",
    "start_date": "2026-07-15T09:00:00Z",
    "end_date": "2026-07-17T17:00:00Z",
    "location": "San Francisco, CA",
    "expected_attendees": 500,
    "topics": ["AI", "agents", "LLMs"]
  }'
```

**Response (201):**
```json
{
  "id": "evt_abc123",
  "name": "AI Builder Hackathon 2026",
  "event_type": "hackathon",
  "description": "48-hour AI hackathon focused on agent development",
  "start_date": "2026-07-15T09:00:00Z",
  "end_date": "2026-07-17T17:00:00Z",
  "location": "San Francisco, CA",
  "expected_attendees": 500,
  "topics": ["AI", "agents", "LLMs"],
  "embedding_id": "emb_xyz789",
  "organizer_id": "usr_owner456",
  "created_at": "2026-06-01T12:00:00Z"
}
```

### GET / -- List Events

List events with advanced filtering and pagination.

**Auth:** None required

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/events/?event_type=hackathon&topics=AI,ML&sort_by=start_date&limit=25"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `event_type` | string | -- | Filter by type (conference, hackathon, workshop, etc.) |
| `topics` | string | -- | Comma-separated topics (AND logic) |
| `start_date_from` | datetime | -- | Events starting after this date |
| `start_date_to` | datetime | -- | Events starting before this date |
| `location` | string | -- | Location keyword (case-insensitive) |
| `min_attendees` | int | -- | Minimum expected attendees |
| `max_attendees` | int | -- | Maximum expected attendees |
| `sort_by` | string | `start_date` | Sort field: `start_date`, `expected_attendees`, `created_at` |
| `sort_order` | string | `asc` | `asc` or `desc` |
| `limit` | int | 25 | Results per page (1-100) |
| `offset` | int | 0 | Number of results to skip |

**Response (200):**
```json
{
  "events": [{ "id": "evt_abc123", "name": "...", "..." : "..." }],
  "total": 42,
  "limit": 25,
  "offset": 0,
  "has_more": true
}
```

### GET /\{event_id\} -- Get Event

Retrieve a specific event by ID.

```bash
curl https://api.ainative.studio/api/v1/paipalooza/events/evt_abc123
```

### PATCH /\{event_id\} -- Update Event

Update event fields. Only the event organizer can update their events.

**Auth:** Bearer token required (organizer)

```bash
curl -X PATCH https://api.ainative.studio/api/v1/paipalooza/events/evt_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_attendees": 750,
    "description": "Updated description with new agenda"
  }'
```

---

## Organizers

Register as an event organizer and track ad revenue.

**Base path:** `/api/v1/paipalooza/organizers`

### POST / -- Create Organizer

Create a new event organizer account with Stripe Connect.

**Auth:** Bearer token required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/organizers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_owner456",
    "organization_name": "AI Events Inc.",
    "contact_email": "organizer@example.com",
    "contact_phone": "+1-555-0123"
  }'
```

**Response (201):**
```json
{
  "id": "org_abc123",
  "user_id": "usr_owner456",
  "organization_name": "AI Events Inc.",
  "contact_email": "organizer@example.com",
  "stripe_connect_account_id": "acct_1234567890",
  "revenue_share_percentage": 60.0,
  "status": "pending",
  "total_revenue_earned": 0.0,
  "total_payouts": 0.0
}
```

### GET /\{organizer_id\} -- Get Organizer

Retrieve organizer profile details.

**Auth:** Bearer token required (owner or admin)

```bash
curl https://api.ainative.studio/api/v1/paipalooza/organizers/org_abc123 \
  -H "Authorization: Bearer $TOKEN"
```

### PATCH /\{organizer_id\} -- Update Organizer

Update organizer information. Revenue share percentage can only be changed by admin.

**Auth:** Bearer token required (owner)

```bash
curl -X PATCH https://api.ainative.studio/api/v1/paipalooza/organizers/org_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "AI Events Global Inc.",
    "contact_email": "new-email@example.com"
  }'
```

### GET /\{organizer_id\}/revenue -- Get Revenue Tracking

Retrieve revenue metrics and payout status.

**Auth:** Bearer token required (owner or admin)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/organizers/org_abc123/revenue?days=30" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `days` | int | 7 | Time range to analyze (1-365 days) |

**Response (200):**
```json
{
  "organizer_id": "org_abc123",
  "total_revenue_earned": 5000.00,
  "total_payouts": 3000.00,
  "pending_balance": 2000.00,
  "payout_eligible": true,
  "payout_threshold": 100.00,
  "revenue_by_event": [
    { "event_id": "evt_abc", "revenue": 3500.00, "impressions": 175000 }
  ],
  "period_impressions": 50000,
  "period_revenue": 1200.00
}
```

---

## Sponsors

Register as a sponsor, manage credits, and track usage.

**Base path:** `/api/v1/paipalooza/sponsors`

### POST /sponsors -- Create Sponsor

Register as a sponsor with Stripe billing.

**Auth:** Bearer token required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/sponsors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_sponsor789",
    "company_name": "TechCorp AI",
    "industry": "artificial_intelligence",
    "website_url": "https://techcorp.ai",
    "contact_email": "ads@techcorp.ai"
  }'
```

**Response (201):**
```json
{
  "id": "spon_xyz789",
  "user_id": "usr_sponsor789",
  "company_name": "TechCorp AI",
  "industry": "artificial_intelligence",
  "stripe_customer_id": "cus_abc123",
  "credits_balance": 0,
  "status": "active"
}
```

### GET /sponsors/\{sponsor_id\} -- Get Sponsor

Retrieve sponsor profile including credit balance.

**Auth:** Bearer token required (owner or admin)

```bash
curl https://api.ainative.studio/api/v1/paipalooza/sponsors/spon_xyz789 \
  -H "Authorization: Bearer $TOKEN"
```

### PATCH /sponsors/\{sponsor_id\} -- Update Sponsor

Update sponsor profile information.

**Auth:** Bearer token required (owner or admin)

```bash
curl -X PATCH https://api.ainative.studio/api/v1/paipalooza/sponsors/spon_xyz789 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "TechCorp AI Labs",
    "website_url": "https://labs.techcorp.ai"
  }'
```

### POST /sponsors/\{sponsor_id\}/purchase-credits -- Purchase Ad Credits

Purchase ad credits via Stripe (1 credit = $1 USD).

**Auth:** Bearer token required (owner or admin)

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/sponsors/spon_xyz789/purchase-credits \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sponsor_id": "spon_xyz789",
    "amount": 500
  }'
```

**Response (200):**
```json
{
  "sponsor_id": "spon_xyz789",
  "amount": 500,
  "stripe_payment_intent_id": "pi_abc123",
  "client_secret": "pi_abc123_secret_def456",
  "status": "pending"
}
```

### GET /sponsors/\{sponsor_id\}/ad-credits -- Get Credits Balance

Get current ad credits balance and usage summary.

**Auth:** Bearer token required (owner or admin)

```bash
curl https://api.ainative.studio/api/v1/paipalooza/sponsors/spon_xyz789/ad-credits \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "sponsor_id": "spon_xyz789",
  "total_purchased": 1500,
  "credits_used": 875,
  "remaining_balance": 625,
  "total_usd_spent": 1500.00,
  "auto_reload_enabled": false,
  "low_balance_alert": false
}
```

### GET /sponsors/\{sponsor_id\}/usage-breakdown -- Get Usage by Campaign

Get credit usage breakdown by campaign with performance metrics.

**Auth:** Bearer token required (owner or admin)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/sponsors/spon_xyz789/usage-breakdown?time_period=last_30_days" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `time_period` | string | `last_30_days` | `last_7_days`, `last_30_days`, `last_90_days`, `all_time` |

### GET /sponsors/\{sponsor_id\}/check-auto-reload -- Check Auto-Reload

Check and trigger auto-reload if conditions are met.

**Auth:** Bearer token required (owner or admin)

```bash
curl https://api.ainative.studio/api/v1/paipalooza/sponsors/spon_xyz789/check-auto-reload \
  -H "Authorization: Bearer $TOKEN"
```

---

## Campaigns

Create and manage ad campaigns with targeting, budgets, and performance analytics.

**Base path:** `/api/v1/paipalooza/ad-campaigns`

### POST / -- Create Campaign

Create a new ad campaign.

**Auth:** Bearer token required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sponsor_id": "spon_xyz789",
    "name": "AI Conference Q1 2026",
    "creative_ids": ["creative_def456"],
    "budget_credits": 1000,
    "start_date": "2026-01-15T00:00:00Z",
    "end_date": "2026-03-31T23:59:59Z",
    "targeting": {
      "event_types": ["conference", "hackathon"],
      "topics": ["AI", "ML"],
      "locations": ["San Francisco", "New York"]
    }
  }'
```

**Response (201):**
```json
{
  "id": "camp_abc123",
  "sponsor_id": "spon_xyz789",
  "name": "AI Conference Q1 2026",
  "status": "draft",
  "creative_ids": ["creative_def456"],
  "budget_credits": 1000,
  "credits_spent": 0,
  "credits_remaining": 1000,
  "start_date": "2026-01-15T00:00:00Z",
  "end_date": "2026-03-31T23:59:59Z",
  "targeting": {
    "event_types": ["conference", "hackathon"],
    "topics": ["AI", "ML"],
    "locations": ["San Francisco", "New York"]
  }
}
```

### GET / -- List Campaigns

List campaigns with advanced filtering, sorting, and pagination.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/?sponsor_id=spon_xyz789&status=active&sort_by=created_at" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sponsor_id` | string | **required** | Filter by sponsor |
| `status` | string | -- | `draft`, `active`, `paused`, `completed`, `cancelled` |
| `creative_id` | string | -- | Filter by creative used |
| `event_type` | string | -- | Filter by targeted event type |
| `start_date_from` | datetime | -- | Campaigns starting on or after |
| `start_date_to` | datetime | -- | Campaigns starting on or before |
| `search` | string | -- | Search in campaign name |
| `sort_by` | string | `created_at` | `created_at`, `start_date`, `budget_credits`, `name` |
| `sort_order` | string | `desc` | `asc` or `desc` |
| `offset` | int | 0 | Pagination offset |
| `limit` | int | 20 | Results per page (max 100) |

### GET /\{campaign_id\} -- Get Campaign

Retrieve campaign details by ID.

```bash
curl https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/camp_abc123 \
  -H "Authorization: Bearer $TOKEN"
```

### PATCH /\{campaign_id\} -- Update Campaign

Update campaign details. Only draft or paused campaigns can be updated.

```bash
curl -X PATCH https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/camp_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Conference Q1-Q2 2026",
    "budget_credits": 2000,
    "end_date": "2026-06-30T23:59:59Z"
  }'
```

### POST /\{campaign_id\}/activate -- Activate Campaign

Transition a draft campaign to active status and start serving ads.

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/camp_abc123/activate \
  -H "Authorization: Bearer $TOKEN"
```

### POST /\{campaign_id\}/pause -- Pause Campaign

Pause an active campaign to stop serving ads. Budget remains reserved.

```bash
curl -X POST "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/camp_abc123/pause?sponsor_id=spon_xyz789" \
  -H "Authorization: Bearer $TOKEN"
```

### POST /\{campaign_id\}/resume -- Resume Campaign

Resume a paused campaign to restart ad serving.

```bash
curl -X POST "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/camp_abc123/resume?sponsor_id=spon_xyz789" \
  -H "Authorization: Bearer $TOKEN"
```

### GET /\{campaign_id\}/preview-targeting -- Preview Targeting

Preview which events match the campaign's targeting criteria before activating.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/camp_abc123/preview-targeting?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "campaign_id": "camp_abc123",
  "targeting": {
    "event_types": ["hackathon"],
    "topics": ["AI"]
  },
  "matching_events": [{ "id": "evt_abc", "name": "AI Hackathon SF" }],
  "total_matched": 12,
  "similarity_scores": { "evt_abc": 0.92 }
}
```

### GET /\{campaign_id\}/performance -- Campaign Performance

Get comprehensive campaign performance dashboard with impressions, clicks, CTR, spend, and breakdowns.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/camp_abc123/performance?time_range=7d&include_creatives=true" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `time_range` | string | `7d` | `24h`, `7d`, `30d`, `custom` |
| `start_date` | datetime | -- | Required if `time_range=custom` |
| `end_date` | datetime | -- | Required if `time_range=custom` |
| `include_creatives` | bool | true | Include per-creative breakdown |
| `include_events` | bool | true | Include per-event breakdown |

**Response (200):**
```json
{
  "campaign": {
    "impressions": 50000,
    "clicks": 1250,
    "completions": 8500,
    "ctr": 2.5,
    "completion_rate": 17.0,
    "total_spend": 750.00,
    "avg_cpm": 15.00,
    "avg_cpc": 0.60
  },
  "by_creative": [{ "creative_id": "creative_def456", "impressions": 50000, "ctr": 2.5 }],
  "by_event": [{ "event_id": "evt_abc123", "impressions": 30000, "revenue": 450.00 }],
  "time_range": "7d",
  "generated_at": "2026-06-03T12:00:00Z"
}
```

### GET /\{campaign_id\}/performance/export -- Export Performance CSV

Export campaign performance metrics as a CSV file.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/camp_abc123/performance/export?time_range=30d" \
  -H "Authorization: Bearer $TOKEN"
```

### GET /creative/\{creative_id\}/performance -- Creative Performance

Get detailed performance analytics for a specific creative.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/creative/creative_def456/performance?time_range=7d" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `time_range` | string | `7d` | `24h`, `7d`, `30d`, `custom` |
| `start_date` | datetime | -- | Required if `time_range=custom` |
| `end_date` | datetime | -- | Required if `time_range=custom` |
| `campaign_id` | string | -- | Filter by specific campaign |
| `include_daily` | bool | true | Include daily time series |
| `include_by_campaign` | bool | true | Include per-campaign breakdown |

### GET /creatives/compare -- Compare Creatives

Compare up to 10 creatives side-by-side, ranked by CTR.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/creatives/compare?creative_ids=cre_1&creative_ids=cre_2&time_range=7d" \
  -H "Authorization: Bearer $TOKEN"
```

### GET /event/\{event_id\}/performance -- Event Performance (Organizer)

Get ad revenue performance for a specific event.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/event/evt_abc123/performance?time_range=30d" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `time_range` | string | `7d` | `24h`, `7d`, `30d`, `custom` |
| `include_daily` | bool | true | Include daily revenue time series |
| `include_sponsors` | bool | true | Include top sponsors breakdown |

### GET /events/compare -- Compare Events

Compare up to 10 events side-by-side, ranked by revenue.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-campaigns/events/compare?event_ids=evt_1&event_ids=evt_2" \
  -H "Authorization: Bearer $TOKEN"
```

---

## Ad Creatives

Upload and manage video, banner, and native ad creatives.

**Base path:** `/api/v1/paipalooza/ad-creatives`

### POST /video -- Upload Video Creative

Upload a video ad creative with full processing pipeline (transcode, thumbnail, VAST XML).

**Auth:** Bearer token required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ad-creatives/video \
  -H "Authorization: Bearer $TOKEN" \
  -F "video_file=@ad-video.mp4" \
  -F "title=AI Conference 2026 Promo" \
  -F "call_to_action=Register Now" \
  -F "destination_url=https://example.com/register" \
  -F "description=Join the largest AI conference" \
  -F "duration_seconds=30"
```

**Response (201):**
```json
{
  "id": "creative_def456",
  "sponsor_id": "spon_xyz789",
  "type": "video",
  "title": "AI Conference 2026 Promo",
  "status": "pending_review",
  "video_url": "https://r2.example.com/videos/original.mp4",
  "transcoded_urls": {
    "720p": "https://r2.example.com/videos/720p.mp4",
    "1080p": "https://r2.example.com/videos/1080p.mp4"
  },
  "thumbnail_url": "https://r2.example.com/thumbnails/thumb.jpg",
  "vast_url": "https://api.ainative.studio/api/v1/paipalooza/ad-creatives/creative_def456/vast.xml",
  "destination_url": "https://example.com/register",
  "call_to_action": "Register Now",
  "duration_seconds": 30
}
```

**Constraints:**
- File size: max 500MB
- Formats: MP4, MOV, WebM
- Duration: 5-120 seconds
- Destination URL must use HTTPS

### POST /banner -- Upload Banner Creative

Upload a banner ad creative with IAB dimension validation.

**Auth:** Bearer token required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ad-creatives/banner \
  -H "Authorization: Bearer $TOKEN" \
  -F "image_file=@banner.png" \
  -F "title=Sponsor Banner Ad" \
  -F "call_to_action=Learn More" \
  -F "destination_url=https://example.com/learn" \
  -F "ad_size=728x90"
```

**IAB Standard Ad Sizes:**

| Size | Name | Use Case |
|------|------|----------|
| `300x250` | Medium Rectangle | Inline content |
| `728x90` | Leaderboard | Top of page |
| `320x50` | Mobile Banner | Mobile web, sticky bottom |
| `160x600` | Wide Skyscraper | Sidebar |
| `970x250` | Billboard | Homepage takeover |

**Constraints:**
- File size: max 5MB
- Formats: JPG, PNG, GIF
- Dimensions must exactly match declared `ad_size`

### POST /native -- Create Native Creative

Create a text-based native ad that blends into content feeds. Image is optional.

**Auth:** Bearer token required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ad-creatives/native \
  -H "Authorization: Bearer $TOKEN" \
  -F "title=Build Smarter AI Agents" \
  -F "description=Join thousands of developers building the next generation of AI agents on our platform" \
  -F "call_to_action=Get Started" \
  -F "destination_url=https://example.com/start" \
  -F "sponsor_name=TechCorp AI" \
  -F "image_file=@native-image.jpg"
```

**Constraints:**
- Title: 10-60 characters
- Description: 30-200 characters
- Call-to-action: max 20 characters
- Image optional (JPG, PNG, GIF, max 5MB)

### GET / -- List Creatives

List all ad creatives for the authenticated sponsor with optional filtering.

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-creatives?type=video&status=pending_review&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `type` | string | -- | `video`, `banner`, `native` |
| `status` | string | -- | `pending_review`, `approved`, `rejected` |
| `skip` | int | 0 | Pagination offset |
| `limit` | int | 20 | Results per page (max 100) |

### GET /\{creative_id\} -- Get Creative

Retrieve detailed information about a specific ad creative.

```bash
curl https://api.ainative.studio/api/v1/paipalooza/ad-creatives/creative_def456 \
  -H "Authorization: Bearer $TOKEN"
```

### PUT /\{creative_id\} -- Update Creative

Update creative metadata. Only `pending_review` creatives can be updated.

**Auth:** Bearer token required (owner)

```bash
curl -X PUT https://api.ainative.studio/api/v1/paipalooza/ad-creatives/creative_def456 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Ad Title",
    "description": "Updated description",
    "call_to_action": "Sign Up",
    "destination_url": "https://example.com/signup"
  }'
```

### DELETE /\{creative_id\} -- Delete Creative

Delete an ad creative. Only `pending_review` creatives can be deleted.

**Auth:** Bearer token required (owner)

```bash
curl -X DELETE https://api.ainative.studio/api/v1/paipalooza/ad-creatives/creative_def456 \
  -H "Authorization: Bearer $TOKEN"
```

**Response:** `204 No Content`

### GET /\{creative_id\}/vast.xml -- Get VAST XML

Retrieve IAB VAST 4.2 compliant XML for video ad serving.

**Auth:** None required (public endpoint for ad players)

```bash
curl https://api.ainative.studio/api/v1/paipalooza/ad-creatives/creative_def456/vast.xml
```

**Response:** `application/xml` with VAST 4.2 XML document.

### POST /\{creative_id\}/review -- Review Creative (Admin)

Admin endpoint to approve or reject a creative.

**Auth:** Bearer token required (admin)

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ad-creatives/creative_def456/review \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approved",
    "notes": "Creative meets all guidelines"
  }'
```

### GET /admin/pending-approvals -- List Pending Approvals (Admin)

List all creatives pending review, ordered by creation date (oldest first).

**Auth:** Bearer token required (superuser)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/ad-creatives/admin/pending-approvals?limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

### POST /admin/approve-creative/\{creative_id\} -- Approve Creative (Admin)

Approve a creative and make it available for ad serving.

**Auth:** Bearer token required (superuser)

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ad-creatives/admin/approve-creative/creative_def456 \
  -H "Authorization: Bearer $TOKEN"
```

### POST /admin/reject-creative/\{creative_id\} -- Reject Creative (Admin)

Reject a creative with a reason.

**Auth:** Bearer token required (superuser)

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ad-creatives/admin/reject-creative/creative_def456 \
  -H "Authorization: Bearer $TOKEN" \
  -F "rejection_reason=Image contains prohibited content and violates advertising guidelines"
```

---

## Ad Serving

Public endpoint for frontends to request ads for event pages.

**Base path:** `/api/v1/paipalooza/ads`

### POST /serve -- Serve Ad

Request an ad for a specific event placement. Called by frontend ad widgets.

**Auth:** None required (public endpoint)

**Rate Limit:** 10,000 requests/minute per IP

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/ads/serve \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_abc123",
    "placement": "header",
    "device_type": "desktop"
  }'
```

**Response (200):**
```json
{
  "ad_id": "ad_xyz789abc123",
  "creative_id": "creative_def456",
  "campaign_id": "camp_abc123",
  "creative_type": "video",
  "creative_data": {
    "title": "AI Conference 2026",
    "video_url": "https://r2.example.com/video.mp4",
    "thumbnail_url": "https://r2.example.com/thumb.jpg",
    "duration_seconds": 30,
    "call_to_action": "Register Now",
    "destination_url": "https://example.com/register"
  },
  "tracking_urls": {
    "impression_url": "https://api.ainative.studio/api/v1/paipalooza/tracking/impression",
    "click_url": "https://api.ainative.studio/api/v1/paipalooza/tracking/click",
    "completion_url": "https://api.ainative.studio/api/v1/paipalooza/tracking/completion"
  }
}
```

**Response (204):** No eligible ads available for this placement.

**Placement types:** `header`, `sidebar`, `content`, `video`

**Device types:** `desktop`, `mobile`, `tablet`

---

## Tracking

Public endpoints for tracking ad impressions, clicks, and video completions. No authentication required (used by tracking pixels).

**Base path:** `/api/v1/paipalooza/tracking`

**Rate Limit:** 1,000 requests/minute per IP (all tracking endpoints)

### POST /impression -- Track Impression

Track when an ad is displayed to a user.

**Auth:** None required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/tracking/impression \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "camp_abc123",
    "creative_id": "creative_def456",
    "event_id": "evt_abc123",
    "placement": "header",
    "user_id": "usr_viewer001"
  }'
```

**Response (201):**
```json
{
  "impression_id": "imp_abc123",
  "campaign_id": "camp_abc123",
  "creative_id": "creative_def456",
  "event_id": "evt_abc123",
  "placement": "header",
  "credits_charged": 0.02,
  "created_at": "2026-06-03T12:00:00Z"
}
```

**Billing by placement type:**

| Placement | Cost per Impression |
|-----------|-------------------|
| Header | $0.02 |
| Sidebar | $0.01 |
| Content | $0.015 |
| Video | $0.03 |
| Footer | $0.005 |

**Error codes:**
- `400` -- Campaign inactive, creative unapproved, or validation failed
- `404` -- Campaign, creative, or event not found
- `409` -- Duplicate impression (same user + campaign within 24h)
- `429` -- Rate limit exceeded

### POST /click -- Track Click

Track when a user clicks on an ad.

**Auth:** None required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/tracking/click \
  -H "Content-Type: application/json" \
  -d '{
    "impression_id": "imp_abc123",
    "campaign_id": "camp_abc123",
    "creative_id": "creative_def456",
    "destination_url": "https://example.com/register"
  }'
```

**Response (201):**
```json
{
  "click_id": "clk_xyz789",
  "impression_id": "imp_abc123",
  "campaign_id": "camp_abc123",
  "time_to_click": 12.5,
  "redirect_url": "https://example.com/register",
  "created_at": "2026-06-03T12:00:12Z"
}
```

### POST /completion -- Track Video Completion

Track video ad completion milestones for engagement metrics. Only applies to video creatives.

**Auth:** None required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/tracking/completion \
  -H "Content-Type: application/json" \
  -d '{
    "impression_id": "imp_abc123",
    "campaign_id": "camp_abc123",
    "creative_id": "creative_def456",
    "milestone": "100"
  }'
```

**Milestone values and engagement scores:**

| Milestone | Engagement Score | Credit Bonus |
|-----------|-----------------|--------------|
| `0` (started) | 0.0 | -- |
| `25` | 0.25 | -- |
| `50` | 0.5 | -- |
| `75` | 0.75 | -- |
| `100` (complete) | 1.0 | $0.01 |

### GET /health -- Tracking Health Check

Check tracking service availability.

```bash
curl https://api.ainative.studio/api/v1/paipalooza/tracking/health
```

---

## Content Inventory

Manage ad slot inventory for events. Organizers define available slots; sponsors browse availability.

**Base path:** `/api/v1/paipalooza/content-inventory`

### POST / -- Create Inventory

Define ad slot inventory for an event.

**Auth:** Bearer token required (event organizer)

```bash
curl -X POST "https://api.ainative.studio/api/v1/paipalooza/content-inventory?event_id=evt_abc123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slot_type": "video_preroll",
    "format": "video",
    "total_slots": 50,
    "floor_price": 5.00,
    "suggested_price": 10.00
  }'
```

**Response (201):**
```json
{
  "id": "inv_abc123",
  "event_id": "evt_abc123",
  "slot_type": "video_preroll",
  "format": "video",
  "total_slots": 50,
  "filled_slots": 0,
  "floor_price": 5.00,
  "suggested_price": 10.00,
  "created_at": "2026-06-01T12:00:00Z"
}
```

**Slot types:** `video_preroll`, `banner_sidebar`, `email_header`, `content_native`, `audio_preroll`

**Formats:** `video`, `banner`, `native`, `audio`

### GET /\{inventory_id\} -- Get Inventory

Retrieve inventory details by ID.

**Auth:** None required

```bash
curl https://api.ainative.studio/api/v1/paipalooza/content-inventory/inv_abc123
```

### GET /events/\{event_id\}/inventory -- List Event Inventory

Browse available ad inventory for an event with real-time availability.

**Auth:** None required (public for sponsors to browse)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/content-inventory/events/evt_abc123/inventory?format=video&sort_by=price"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `format` | string | -- | Filter by format: `video`, `banner`, `native`, `audio` |
| `sort_by` | string | `price` | `price` or `availability` |
| `sort_order` | string | `asc` | `asc` or `desc` |
| `limit` | int | 25 | Results per page (1-100) |
| `offset` | int | 0 | Results to skip |

**Response (200):**
```json
{
  "items": [
    {
      "id": "inv_abc123",
      "slot_type": "video_preroll",
      "format": "video",
      "total_slots": 50,
      "filled_slots": 12,
      "available_slots": 38,
      "floor_price": 5.00,
      "suggested_price": 10.00
    }
  ],
  "total": 5,
  "has_more": false
}
```

---

## Pricing

Dynamic pricing engine for ad inventory estimates.

**Base path:** `/api/v1/paipalooza/pricing`

### GET /estimate -- Get Pricing Estimate

Calculate suggested bid (eCPM) with dynamic pricing based on event size, scarcity, and targeting.

**Auth:** None required (public endpoint)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/pricing/estimate?event_id=1&format=video&expected_attendees=500&fill_rate=0.8&targeting_specificity=0.5"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `event_id` | int | **required** | Event ID to price inventory for |
| `format` | string | **required** | `video`, `banner`, `native`, `audio` |
| `targeting_specificity` | float | 0.0 | 0.0 (broad) to 1.0 (highly targeted) |
| `expected_attendees` | int | 100 | Expected number of attendees |
| `fill_rate` | float | 0.0 | Current inventory fill rate (0.0-1.0) |

**Response (200):**
```json
{
  "base_price": 10.0,
  "adjusted_price": 24.15,
  "factors": {
    "base_price": 10.0,
    "attendees_multiplier": 1.5,
    "scarcity_multiplier": 1.4,
    "targeting_multiplier": 1.15
  },
  "suggested_ecpm": 24.15,
  "event_id": 1,
  "format": "video"
}
```

**Base prices by format:**

| Format | Base eCPM |
|--------|-----------|
| Video | $10.00 |
| Audio | $7.00 |
| Native | $5.00 |
| Banner | $3.00 |

**Pricing factors:**
- **Event size:** Larger events command higher prices
- **Inventory scarcity:** Prices increase as inventory fills
- **Targeting specificity:** More targeted ads cost more

---

## Payouts

Stripe-powered payout processing for organizers.

**Base path:** `/api/v1/paipalooza/payouts`

### POST /process -- Process Pending Payouts (Admin)

Process all pending payouts for eligible organizers. Designed for scheduled jobs or manual admin triggers.

**Auth:** Bearer token required (admin)

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/payouts/process \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "total_organizers_checked": 25,
  "eligible_organizers": 8,
  "successful_payouts": 7,
  "failed_payouts": 1,
  "total_amount_paid": 4250.00,
  "errors": ["Organizer org_fail: Stripe Connect account not active"]
}
```

### POST /manual -- Create Manual Payout (Admin)

Manually trigger a payout for a specific organizer.

**Auth:** Bearer token required (admin)

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/payouts/manual \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizer_id": "org_abc123",
    "override_threshold": false
  }'
```

**Response (201):**
```json
{
  "payout_id": "pay_xyz789",
  "organizer_id": "org_abc123",
  "amount": 2000.00,
  "status": "completed",
  "stripe_payout_id": "po_1234567890",
  "created_at": "2026-06-03T12:00:00Z",
  "completed_at": "2026-06-03T12:00:05Z"
}
```

### GET /eligibility/\{organizer_id\} -- Check Eligibility

Check if an organizer is eligible for payout.

**Auth:** Bearer token required (owner or admin)

```bash
curl https://api.ainative.studio/api/v1/paipalooza/payouts/eligibility/org_abc123 \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "organizer_id": "org_abc123",
  "pending_balance": 2000.00,
  "payout_threshold": 100.00,
  "eligible": true,
  "reason": null
}
```

**Eligibility criteria:**
- Pending balance >= $100.00
- Valid Stripe Connect account
- Account status is active

### GET /history/\{organizer_id\} -- Get Payout History

Retrieve payout transaction history for an organizer.

**Auth:** Bearer token required (owner or admin)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/payouts/history/org_abc123?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | int | 100 | Maximum records (1-1000) |

**Response (200):**
```json
[
  {
    "payout_id": "pay_xyz789",
    "amount": 2000.00,
    "status": "completed",
    "stripe_payout_id": "po_1234567890",
    "created_at": "2026-06-03T12:00:00Z",
    "completed_at": "2026-06-03T12:00:05Z",
    "failure_reason": null
  }
]
```

---

## Hackathon Proxy

Proxy endpoints for the dotHack hackathon discovery API.

**Base path:** `/api/v1/paipalooza/hackathon`

### GET /events -- List Hackathons

List hackathons with filtering by topic, location, format, and date range.

**Auth:** None required

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/hackathon/events?topic=ai_ml&format=in_person&limit=20"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `topic` | string | -- | `ai_ml`, `web3`, `fintech`, etc. |
| `location` | string | -- | City or country filter |
| `format` | string | -- | `in_person`, `virtual`, `hybrid` |
| `start_date` | date | -- | Hackathons starting after this date |
| `end_date` | date | -- | Hackathons starting before this date |
| `include_past` | bool | false | Include past hackathons |
| `limit` | int | 50 | Max results (1-100) |
| `offset` | int | 0 | Pagination offset |

**Response (200):**
```json
{
  "hackathons": [
    {
      "id": "hack_abc123",
      "name": "AI Agents Hackathon",
      "topic": "ai_ml",
      "format": "in_person",
      "location": "San Francisco, CA",
      "start_date": "2026-07-15",
      "end_date": "2026-07-17"
    }
  ],
  "total_count": 42,
  "has_more": true,
  "cached": false
}
```

### GET /events/\{hackathon_id\} -- Get Hackathon

Get details for a specific hackathon.

```bash
curl https://api.ainative.studio/api/v1/paipalooza/hackathon/events/hack_abc123
```

---

## Luma Integration

Import and sync events from Luma (lu.ma) into PAI Palooza.

**Base path:** `/api/v1/paipalooza/luma`

### POST /authorize -- Authorize Luma API

Verify Luma API credentials and check access to events.

**Auth:** Bearer token required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/luma/authorize \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "luma_key_abc123",
    "organizer_id": "org_abc123"
  }'
```

**Response (200):**
```json
{
  "authorized": true,
  "luma_user_id": "luma_usr_xyz",
  "events_count": 15,
  "error": null
}
```

### GET /events -- List Luma Events

List events from Luma for the organizer.

**Auth:** Bearer token required

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/luma/events?organizer_id=org_abc123&include_past=false&limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `organizer_id` | string | **required** | PAI Palooza organizer ID |
| `include_past` | bool | false | Include past events |
| `limit` | int | 50 | Max events (1-100) |

### POST /import -- Import Luma Event

Import a Luma event into PAI Palooza with field mapping and embedding generation.

**Auth:** Bearer token required

```bash
curl -X POST https://api.ainative.studio/api/v1/paipalooza/luma/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "luma_event_id": "luma_evt_abc123",
    "organizer_id": "org_abc123",
    "expected_attendees": 200,
    "categories": ["AI", "hackathon"]
  }'
```

**Response (201):**
```json
{
  "success": true,
  "pai_event_id": "evt_new456",
  "luma_event_id": "luma_evt_abc123",
  "status": "imported",
  "error": null
}
```

### POST /\{pai_event_id\}/sync -- Sync from Luma

Sync a PAI Palooza event with its Luma source to pull latest changes.

**Auth:** Bearer token required

```bash
curl -X POST "https://api.ainative.studio/api/v1/paipalooza/luma/evt_new456/sync?force_update=false" \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "success": true,
  "pai_event_id": "evt_new456",
  "luma_event_id": "luma_evt_abc123",
  "updated_fields": ["description", "expected_attendees"],
  "status": "synced",
  "synced_at": "2026-06-03T12:00:00Z",
  "error": null
}
```

---

## Admin

Platform-wide admin dashboard and revenue reporting.

**Base path:** `/api/v1/paipalooza/admin`

### GET /dashboard -- Admin Dashboard

Get platform-wide metrics for the admin dashboard.

**Auth:** Bearer token required (admin)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/admin/dashboard?include_sponsors=true&include_events=true&growth_period=mom" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `include_sponsors` | bool | true | Include top sponsors |
| `include_events` | bool | true | Include top events |
| `include_growth` | bool | true | Include growth metrics |
| `sponsors_limit` | int | 5 | Number of top sponsors (1-20) |
| `events_limit` | int | 5 | Number of top events (1-20) |
| `growth_period` | string | `mom` | Growth comparison: `mom` (month), `yoy` (year), `wow` (week) |

**Response (200):**
```json
{
  "active_campaigns": 45,
  "pending_campaigns": 12,
  "impressions_24h": 150000,
  "impressions_7d": 980000,
  "impressions_30d": 3500000,
  "platform_revenue": 52500.00,
  "organizer_revenue": 78750.00,
  "pending_approvals": 8,
  "top_sponsors": [
    { "sponsor_id": "spon_xyz789", "company_name": "TechCorp AI", "spend": 15000.00 }
  ],
  "top_events": [
    { "event_id": "evt_abc123", "name": "AI Hackathon SF", "revenue": 8500.00 }
  ],
  "growth": {
    "impressions_growth": 15.2,
    "revenue_growth": 22.5,
    "period": "mom"
  }
}
```

### GET /revenue-report -- Revenue Report

Get detailed revenue report with breakdowns by event, sponsor, and date.

**Auth:** Bearer token required (admin)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/admin/revenue-report?start_date=2026-05-01&end_date=2026-05-31&include_daily=true" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `start_date` | date | -- | Start date filter |
| `end_date` | date | -- | End date filter |
| `include_events` | bool | true | Include event breakdown |
| `include_sponsors` | bool | true | Include sponsor breakdown |
| `include_daily` | bool | true | Include daily breakdown |
| `events_limit` | int | 10 | Max events (1-50) |
| `sponsors_limit` | int | 10 | Max sponsors (1-50) |

**Response (200):**
```json
{
  "total_platform_revenue": 52500.00,
  "total_organizer_payouts": 35000.00,
  "pending_organizer_balances": 43750.00,
  "by_event": [
    { "event_id": "evt_abc", "name": "AI Hackathon", "revenue": 8500.00 }
  ],
  "by_sponsor": [
    { "sponsor_id": "spon_xyz", "company": "TechCorp", "spend": 15000.00 }
  ],
  "by_date": [
    { "date": "2026-05-01", "revenue": 1750.00, "impressions": 50000 }
  ]
}
```

### GET /revenue-report/export -- Export Revenue CSV

Export revenue report as a CSV file for accounting.

**Auth:** Bearer token required (admin)

```bash
curl "https://api.ainative.studio/api/v1/paipalooza/admin/revenue-report/export?start_date=2026-05-01&end_date=2026-05-31" \
  -H "Authorization: Bearer $TOKEN" \
  -o revenue-report.csv
```

**Response:** CSV file download with columns: date, event, sponsor, campaign, revenue, platform_share, organizer_share.

---

## Error Responses

All endpoints return errors in a consistent format:

```json
{
  "detail": "Human-readable error message"
}
```

**Common HTTP status codes:**

| Code | Meaning |
|------|---------|
| `400` | Bad request -- invalid parameters or business rule violation |
| `401` | Unauthorized -- missing or invalid Bearer token |
| `402` | Payment required -- insufficient credits |
| `403` | Forbidden -- not authorized for this resource |
| `404` | Not found -- resource does not exist |
| `409` | Conflict -- duplicate resource (e.g., duplicate impression) |
| `422` | Validation error -- request body failed schema validation |
| `429` | Rate limit exceeded |
| `500` | Internal server error |