This document defines the complete event schema, including all fields, validation rules, and configuration options. Use this as a reference for API integrations or understanding event data structure.
Event Object Schema
json
{
"id": "evt_abc123", // Unique identifier (read-only)
"slug": "summer-retreat-2025", // URL-safe identifier
"title": "Summer Retreat", // Required, 1-100 chars
"description": "...", // HTML allowed, max 50,000 chars
"status": "published", // draft | published | cancelled
"start_date": "2025-07-15T09:00:00Z", // ISO 8601
"end_date": "2025-07-17T17:00:00Z", // ISO 8601
"timezone": "America/Los_Angeles", // IANA timezone
"venue": {
"name": "Sunrise Center",
"address": "123 Peace Lane",
"city": "Sedona",
"state": "AZ",
"country": "US",
"postal_code": "86336",
"lat": 34.8697,
"lng": -111.7610
},
"is_online": false,
"online_url": null, // Required if is_online: true
"image_url": "https://...", // 1920x1080 recommended
"category": "retreat",
"tags": ["yoga", "meditation"],
"organizer_id": "org_xyz789",
"created_at": "2025-01-01T...",
"updated_at": "2025-01-15T..."
}Visual event schema diagram
Interactive component coming soon
Required Fields
Always Required
•title (string, 1-100 characters)
•start_date (ISO 8601 datetime)
•timezone (IANA timezone string)
•organizer_id (your account ID)
Conditional Requirements
•end_date required if multi-day event
•venue.address required if not online
•online_url required if is_online: true
Auto-Generated
•id (system-assigned UUID)
•slug (derived from title if not provided)
•created_at, updated_at (timestamps)
Field Validation Rules
title
Min: 1 character | Max: 100 characters
Allowed: Letters, numbers, spaces, basic punctuation
Stripped: HTML tags, emoji (in URL slug)
description
Max: 50,000 characters
Allowed: HTML (sanitized), markdown
Blocked: Scripts, iframes, external images
start_date / end_date
Format: ISO 8601 with timezone
Validation: end_date must be after start_date
Minimum: 1 hour in the future (new events)
image_url
Formats: JPG, PNG, WebP
Recommended: 1920x1080px
Max file size: 10MB
CDN: Automatically optimized
Interactive event builder preview
Interactive component coming soon
Event Status Transitions
Draft → Published Requirements: All required fields, at least one ticket type, Stripe connected
Published → Cancelled Effect: No new sales, existing tickets remain valid, optional auto-refund
Cancelled → Published Not allowed. Create a new event instead.
Any → Draft Only allowed if zero tickets sold.
Use the slug field for SEO-friendly URLs. If not provided, it's auto-generated from the title. Custom slugs must be unique within your account.