Festivalism API Documentation

Welcome to the Festivalism API documentation. This guide will help you integrate with the Festivalism platform to build applications that interact with festivals, artists, users, and more.

Getting Started

The Festivalism API is a RESTful API that provides access to festival data, artist information, user management, rewards, payments, and real-time notifications. To get started, you'll need to:

1. Create a Client Application — Register your application to get API credentials
2. Authenticate — Obtain authentication tokens for your client and users
3. Make API Requests — Start making requests to our endpoints

Quick Start

1. Create a Client

First, create a client application to get your credentials. You can do this through the Client Management page or via the API.

2. Get Client Credentials

After creating a client, you'll receive:

• Client ID: A unique identifier for your application
• Client Secret: A secret key used for authentication (save this securely — it is shown only once!)

3. Authenticate Your Client

Use your client credentials to obtain a client token:

curl -X POST https://api.festivalism.com/auth/client \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

4. Make API Requests

Use the client token in the X-F-Authorization header for all API requests:

curl -X GET https://api.festivalism.com/festivals \
  -H "X-F-Authorization: your-client-token"

Authentication

The Festivalism API uses a two-tier authentication system:

1. Client Authentication (X-F-Authorization): Required for all API endpoints (except a few public ones like search and artist listing)
2. User Authentication (X-F-Authentication): Required for user-specific operations such as creating festivals, managing tickets, and accessing rewards

See the Authentication Guide for detailed information.

Base URL

All API requests should be made to:

https://api.festivalism.com

For local development:

http://localhost:3000

What You Can Build

The Festivalism API covers the full lifecycle of a festival platform:

Resource	Description
Festivals	Create, list, and manage festivals with venues, photos, and coordinates
Gigs	Artist performance slots with stage, time, and lineup data
Artists	Artist profiles with bios, genres, and social links (Spotify, SoundCloud, YouTube)
Tickets	Festival ticket tiers with pricing, quantities, and sale windows
Payments	Stripe-backed payments for tickets and subscriptions with QR-code validation
Rewards	Gamification system — points, levels, badges, and external challenges
Notifications	Real-time updates via Server-Sent Events (SSE) and push notifications
Users	User accounts, profiles, interests, and role-based access
Search	Global search across artists, festivals, and genres

Rate Limiting

API request limits depend on your plan:

Plan	Monthly Requests
Base	10,000
Pro	50,000
Max	500,000

See the Pricing page for full plan details including festival creation limits and access scope.

Response Format

All responses are JSON. List endpoints return a paginated envelope:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasMore": true
  }
}

Errors follow a consistent structure:

{
  "error": "Human-readable message",
  "details": "..."
}

Support

Need help? Check out our API Reference or contact our support team.