Skip to main content

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)

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):

{
  "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

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

Query Parameters:

ParameterTypeDefaultDescription
event_typestring--Filter by type (conference, hackathon, workshop, etc.)
topicsstring--Comma-separated topics (AND logic)
start_date_fromdatetime--Events starting after this date
start_date_todatetime--Events starting before this date
locationstring--Location keyword (case-insensitive)
min_attendeesint--Minimum expected attendees
max_attendeesint--Maximum expected attendees
sort_bystringstart_dateSort field: start_date, expected_attendees, created_at
sort_orderstringascasc or desc
limitint25Results per page (1-100)
offsetint0Number of results to skip

Response (200):

{
  "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.

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)

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

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):

{
  "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)

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)

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)

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

Query Parameters:

ParameterTypeDefaultDescription
daysint7Time range to analyze (1-365 days)

Response (200):

{
  "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

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):

{
  "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)

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)

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)

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):

{
  "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)

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

Response (200):

{
  "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)

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

Query Parameters:

ParameterTypeDefaultDescription
time_periodstringlast_30_dayslast_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)

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

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):

{
  "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.

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:

ParameterTypeDefaultDescription
sponsor_idstringrequiredFilter by sponsor
statusstring--draft, active, paused, completed, cancelled
creative_idstring--Filter by creative used
event_typestring--Filter by targeted event type
start_date_fromdatetime--Campaigns starting on or after
start_date_todatetime--Campaigns starting on or before
searchstring--Search in campaign name
sort_bystringcreated_atcreated_at, start_date, budget_credits, name
sort_orderstringdescasc or desc
offsetint0Pagination offset
limitint20Results per page (max 100)

GET /{campaign_id} -- Get Campaign​

Retrieve campaign details by ID.

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.

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.

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.

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.

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.

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

Response (200):

{
  "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.

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:

ParameterTypeDefaultDescription
time_rangestring7d24h, 7d, 30d, custom
start_datedatetime--Required if time_range=custom
end_datedatetime--Required if time_range=custom
include_creativesbooltrueInclude per-creative breakdown
include_eventsbooltrueInclude per-event breakdown

Response (200):

{
  "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.

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.

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

Query Parameters:

ParameterTypeDefaultDescription
time_rangestring7d24h, 7d, 30d, custom
start_datedatetime--Required if time_range=custom
end_datedatetime--Required if time_range=custom
campaign_idstring--Filter by specific campaign
include_dailybooltrueInclude daily time series
include_by_campaignbooltrueInclude per-campaign breakdown

GET /creatives/compare -- Compare Creatives​

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

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.

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

Query Parameters:

ParameterTypeDefaultDescription
time_rangestring7d24h, 7d, 30d, custom
include_dailybooltrueInclude daily revenue time series
include_sponsorsbooltrueInclude top sponsors breakdown

GET /events/compare -- Compare Events​

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

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

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):

{
  "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

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:

SizeNameUse Case
300x250Medium RectangleInline content
728x90LeaderboardTop of page
320x50Mobile BannerMobile web, sticky bottom
160x600Wide SkyscraperSidebar
970x250BillboardHomepage 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

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.

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

Query Parameters:

ParameterTypeDefaultDescription
typestring--video, banner, native
statusstring--pending_review, approved, rejected
skipint0Pagination offset
limitint20Results per page (max 100)

GET /{creative_id} -- Get Creative​

Retrieve detailed information about a specific ad creative.

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)

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)

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)

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)

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)

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)

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)

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

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):

{
  "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

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):

{
  "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:

PlacementCost 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

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):

{
  "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

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:

MilestoneEngagement ScoreCredit Bonus
0 (started)0.0--
250.25--
500.5--
750.75--
100 (complete)1.0$0.01

GET /health -- Tracking Health Check​

Check tracking service availability.

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)

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):

{
  "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

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)

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

Query Parameters:

ParameterTypeDefaultDescription
formatstring--Filter by format: video, banner, native, audio
sort_bystringpriceprice or availability
sort_orderstringascasc or desc
limitint25Results per page (1-100)
offsetint0Results to skip

Response (200):

{
  "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)

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:

ParameterTypeDefaultDescription
event_idintrequiredEvent ID to price inventory for
formatstringrequiredvideo, banner, native, audio
targeting_specificityfloat0.00.0 (broad) to 1.0 (highly targeted)
expected_attendeesint100Expected number of attendees
fill_ratefloat0.0Current inventory fill rate (0.0-1.0)

Response (200):

{
  "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:

FormatBase 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)

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

Response (200):

{
  "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)

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):

{
  "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)

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

Response (200):

{
  "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)

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

Query Parameters:

ParameterTypeDefaultDescription
limitint100Maximum records (1-1000)

Response (200):

[
  {
    "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

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

Query Parameters:

ParameterTypeDefaultDescription
topicstring--ai_ml, web3, fintech, etc.
locationstring--City or country filter
formatstring--in_person, virtual, hybrid
start_datedate--Hackathons starting after this date
end_datedate--Hackathons starting before this date
include_pastboolfalseInclude past hackathons
limitint50Max results (1-100)
offsetint0Pagination offset

Response (200):

{
  "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.

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

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):

{
  "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

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:

ParameterTypeDefaultDescription
organizer_idstringrequiredPAI Palooza organizer ID
include_pastboolfalseInclude past events
limitint50Max 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

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):

{
  "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

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

Response (200):

{
  "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)

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:

ParameterTypeDefaultDescription
include_sponsorsbooltrueInclude top sponsors
include_eventsbooltrueInclude top events
include_growthbooltrueInclude growth metrics
sponsors_limitint5Number of top sponsors (1-20)
events_limitint5Number of top events (1-20)
growth_periodstringmomGrowth comparison: mom (month), yoy (year), wow (week)

Response (200):

{
  "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)

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:

ParameterTypeDefaultDescription
start_datedate--Start date filter
end_datedate--End date filter
include_eventsbooltrueInclude event breakdown
include_sponsorsbooltrueInclude sponsor breakdown
include_dailybooltrueInclude daily breakdown
events_limitint10Max events (1-50)
sponsors_limitint10Max sponsors (1-50)

Response (200):

{
  "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)

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:

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

Common HTTP status codes:

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