vihaya-events 0.1.1

Official Python SDK for the Vihaya Events platform. Fetch events, register attendees, and verify Razorpay payments with a fully-typed client.

Vihaya SDK for Python — Official vihaya-events Client

vihaya-events is the official Python SDK for the Vihaya Events platform. Build event listings, attendee registration flows, Razorpay payment verification, ticketing dashboards, analytics pipelines, and backend integrations in Django, Flask, FastAPI, Starlette, Pyramid, Jupyter notebooks, or any Python 3.9+ runtime — all with full Pydantic v2 type safety and idiomatic Python ergonomics.

Vihaya is the modern events platform for India — a single stack for event organisers, ticketing, sponsor management, attendee registration, live check-in, and real-time analytics. This SDK is the fastest way to integrate the Vihaya Events API (https://events.vihaya.app) into any Python codebase.

---

Table of contents

• What is Vihaya?
• Why the Vihaya Python SDK?
• The Vihaya SDK family
• Installation
• Get your Vihaya API key
• Quick start
• Core concepts
• Usage guide
• Framework integrations
• Mega events & sub-events
• Razorpay payment flow
• API reference
• Models
• Error handling
• Security best practices
• FAQ
• Keywords
• Development
• Contributing
• License

---

🇮🇳 What is Vihaya?

Vihaya is an all-in-one events platform for India, built for organisers who run college fests, hackathons, conferences, workshops, meetups, bootcamps, summits, and corporate events. The Vihaya platform provides:

• 🎟️ Event creation & ticketing with pricing tiers (Early Bird, Student, VIP, Group), promo codes, and a fully-hosted checkout.
• 🏢 Mega events — bundle dozens of sub-events (workshops, competitions, talks) under one parent fest.
• 💳 Razorpay payments — integrated end-to-end with server-side signature verification.
• 📋 Custom registration fields — T-shirt size, college name, team members, dietary preferences, accommodation, and more.
• 👥 Attendee management — real-time registrations, bulk email, WhatsApp broadcasts, CSV exports.
• 📱 Live check-in — mobile QR scanning with offline-first sync.
• 👩‍🏫 Speakers, agenda, sponsors, FAQs — everything needed for a rich public event page.
• 📊 Analytics — registrations over time, revenue, tier breakdowns, funnel tracking.
• 🔔 Broadcasts — push updates to all attendees via email, SMS, and WhatsApp.

The Vihaya Events API — and this vihaya-events package — lets Python developers embed that platform into their own backend services, data pipelines, Django sites, FastAPI microservices, Streamlit dashboards, and Jupyter notebooks.

Production URL: https://events.vihaya.app · Marketing site: https://vihaya.app · Developer dashboard: https://events.vihaya.app/profile/developer

---

✨ Why the Vihaya Python SDK?

• 🔐 Fully typed — every response is a Pydantic v2 model with autocomplete and runtime validation.
• ⚡ Built on httpx — HTTP/2 support, connection pooling, and both sync and async-friendly design.
• 🐍 Pythonic — snake_case everywhere, context-manager support, idiomatic error handling.
• 📦 Small surface — Vihaya, RegisterData, VihayaError — learn it in one sitting.
• 🧪 Tested against the live events.vihaya.app production API on every release.
• 🎛️ Forward-compatible — Pydantic extra="allow" preserves new fields the server adds between releases.
• 🧩 Plays nicely with Django, Flask, FastAPI, Starlette, Litestar, Celery, Airflow, and Jupyter.
• 💳 Razorpay ready — events.register() → Razorpay → payments.verify() in three lines.

---

🌍 The Vihaya SDK family (7 languages)

The Vihaya Events API has seven official SDKs — all feature-compatible, all maintained in lockstep, all talking to the same events.vihaya.app production API.

Language	Package	Repository	Install
🐍 Python	vihaya-events	Vishnu252005/vihaya-sdk-python	pip install vihaya-events
🟨 JavaScript / TypeScript	vihaya-sdk	Vishnu252005/vihaya-sdk	npm install vihaya-sdk
🦫 Go	vihaya-sdk-go	Vishnu252005/vihaya-sdk-go	go get github.com/Vishnu252005/vihaya-sdk-go
☕ Java	vihaya-sdk-java	Vishnu252005/vihaya-sdk-java	JitPack / Gradle / Maven
💎 Ruby	vihaya-events	Vishnu252005/vihaya-sdk-ruby	gem install vihaya-events
🐘 PHP	vihaya/events	Vishnu252005/vihaya-sdk-php	composer require vihaya/events
📱 Flutter / Dart	vihaya_sdk_flutter	Vishnu252005/vihaya-sdk-flutter	flutter pub add vihaya_sdk_flutter

All Vihaya SDKs target the same API base URL (https://events.vihaya.app), authenticate with the same x-api-key header, and expose the same methods: events.list(), events.get(), events.register(), payments.verify().

---

📦 Installation

pip install vihaya-events

Or with your favourite tool:

poetry add vihaya-events
pipenv install vihaya-events
uv add vihaya-events
pdm add vihaya-events
conda install -c conda-forge vihaya-events   # coming soon

Requirements:

• Python 3.9, 3.10, 3.11, 3.12, 3.13+
• httpx >= 0.27
• pydantic >= 2.5

Install name: vihaya-events. Import name: vihaya.

from vihaya import Vihaya, RegisterData, VihayaError

---

🔑 Get your Vihaya API key

1. Sign up or log in at events.vihaya.app.
2. Open the Developer Dashboard.
3. Click Generate API Key and copy the vh_live_... token.
4. Store it in an environment variable — never commit it to git.

export VIHAYA_API_KEY=vh_live_xxxxxxxxxxxxxxxxxxxxxxxx

---

🚀 Quick start

import os
from vihaya import Vihaya

vh = Vihaya(os.environ["VIHAYA_API_KEY"])

for event in vh.events.list():
    print(f"{event.title} — {event.location} on {event.date}")

Use it as a context manager to guarantee the HTTP connection pool is closed cleanly:

with Vihaya("vh_live_...") as vh:
    event = vh.events.get("evt_8x42j9")
    print(event.title, event.date, event.location)

Register an attendee

from vihaya import RegisterData

data = RegisterData(
    name="Anjali Mehta",
    email="[e-mail]",
    phone="[phone]",
    custom_fields={"T-Shirt Size": "L", "College": "Vihaya Institute"},
)

result = vh.events.register("evt_8x42j9", data)

if result.get("isPaid"):
    print("Razorpay order ID:", result["orderId"])
else:
    print("Free registration confirmed:", result["registrationId"])

Verify a Razorpay payment (server-side)

vh.payments.verify(
    payment_id="pay_O8K2...",
    order_id=result["orderId"],
    signature="signature_from_razorpay",
)

---

🧭 Core concepts

Events

Every record in Vihaya is an Event — title, description, date, venue, banner, tiers, custom fields, speakers, agenda, sponsors, FAQs, and sub-events. The Python SDK models this as a vihaya.Event Pydantic model.

Mega events

A mega event is a parent event that contains multiple sub-events. A college fest with 40 workshops is one mega event with 40 sub-events. Access them via event.sub_events.

Registrations

A registration is an attendee entry — free or paid, with optional custom fields, team members, dietary preferences, and accommodation. Submit via events.register().

Payments

Paid registrations create a Razorpay order; verify the callback signature via payments.verify() on your backend.

API key

All Vihaya requests authenticate via the x-api-key header. Keep your vh_live_... key in an env var, a secrets manager, or your cloud KMS — never in source.

---

📚 Usage guide

Fetch a full event

events.get() returns an Event with every piece of metadata the organiser has configured — speakers, agenda, sponsors, FAQs, custom fields, pricing tiers, and sub-events.

event = vh.events.get("evt_8x42j9")

print(event.title)
print(f"Mode: {event.event_mode}  Timezone: {event.timezone}")
print(f"Location: {event.location}")
print(f"Date: {event.date} {event.time}")

for speaker in event.speaker_list or []:
    print(f"- {speaker.name} ({speaker.role}) @ {speaker.company}")

for item in event.agenda_list or []:
    print(f"[{item.time}] {item.title} — {item.speaker}")

for sponsor in event.sponsors or []:
    print(f"{sponsor.name} ({sponsor.tier})")

for faq in event.faqs or []:
    print(f"Q: {faq.question}\nA: {faq.answer}\n")

for tier in event.special_prices or []:
    print(f"  {tier.name}: ₹{tier.amount}")

for field in event.custom_fields or []:
    print(f"  {field.name} [{field.type}] required={field.required}")

List & filter events

events = vh.events.list()

# Upcoming only
from datetime import datetime
upcoming = [e for e in events if datetime.fromisoformat(e.date) > datetime.now()]

# Mega events
mega = [e for e in events if e.event_type == "megaEvent"]

# Free events
free = [e for e in events if e.is_free]

# Online events
online = [e for e in events if e.event_mode == "online"]

Register a paid attendee with tiers, custom fields, and promo code

result = vh.events.register(
    "evt_8x42j9",
    RegisterData(
        name="Priya Raj",
        email="[e-mail]",
        phone="[phone]",
        tier="Early Bird",
        promo_code="LAUNCH10",
        custom_fields={
            "College": "IIT Bombay",
            "T-Shirt Size": "M",
            "Year of Study": "3rd",
        },
    ),
)

Register a team for a hackathon

result = vh.events.register(
    "evt_hackathon_2026",
    {
        "name": "Team Lead",
        "email": "[e-mail]",
        "phone": "[phone]",
        "teamName": "Byte Squad",
        "teamMembers": [
            {"name": "Alice", "email": "[e-mail]", "phone": "+91..."},
            {"name": "Bob",   "email": "[e-mail]",   "phone": "+91..."},
            {"name": "Carol", "email": "[e-mail]", "phone": "+91..."},
        ],
    },
)

You can always pass a plain dict instead of RegisterData — camelCase keys go straight to the API.

---

🎨 Framework integrations

Django view

# views.py
from django.http import JsonResponse
from django.conf import settings
from vihaya import Vihaya

def event_list(request):
    with Vihaya(settings.VIHAYA_API_KEY) as vh:
        events = vh.events.list()
    return JsonResponse([e.model_dump() for e in events], safe=False)

def event_detail(request, event_id):
    with Vihaya(settings.VIHAYA_API_KEY) as vh:
        event = vh.events.get(event_id)
    return JsonResponse(event.model_dump())

Django REST Framework view

from rest_framework.views import APIView
from rest_framework.response import Response
from django.conf import settings
from vihaya import Vihaya, RegisterData, VihayaError

class RegisterView(APIView):
    def post(self, request, event_id):
        try:
            with Vihaya(settings.VIHAYA_API_KEY) as vh:
                result = vh.events.register(
                    event_id,
                    RegisterData(**request.data),
                )
            return Response(result)
        except VihayaError as e:
            return Response({"error": e.message}, status=e.status or 500)

Flask

from flask import Flask, jsonify, request
from vihaya import Vihaya, RegisterData

app = Flask(__name__)
vh = Vihaya(os.environ["VIHAYA_API_KEY"])

@app.get("/events")
def list_events():
    return jsonify([e.model_dump() for e in vh.events.list()])

@app.post("/events/<event_id>/register")
def register(event_id):
    data = RegisterData(**request.json)
    return jsonify(vh.events.register(event_id, data))

FastAPI

from fastapi import FastAPI, Depends, HTTPException
from vihaya import Vihaya, RegisterData, VihayaError

app = FastAPI()

def get_vihaya() -> Vihaya:
    return Vihaya(os.environ["VIHAYA_API_KEY"])

@app.get("/events")
def list_events(vh: Vihaya = Depends(get_vihaya)):
    return vh.events.list()

@app.get("/events/{event_id}")
def get_event(event_id: str, vh: Vihaya = Depends(get_vihaya)):
    try:
        return vh.events.get(event_id)
    except VihayaError as e:
        raise HTTPException(status_code=e.status or 500, detail=e.message)

@app.post("/events/{event_id}/register")
def register(event_id: str, data: RegisterData, vh: Vihaya = Depends(get_vihaya)):
    return vh.events.register(event_id, data)

Celery background task

from celery import shared_task
from vihaya import Vihaya, RegisterData

@shared_task
def process_registration(event_id: str, payload: dict):
    with Vihaya(os.environ["VIHAYA_API_KEY"]) as vh:
        return vh.events.register(event_id, RegisterData(**payload))

Jupyter notebook / Streamlit dashboard

import pandas as pd
from vihaya import Vihaya

with Vihaya("vh_live_...") as vh:
    events = vh.events.list()

df = pd.DataFrame([e.model_dump() for e in events])
df[["title", "date", "location", "price", "event_mode"]]

---

🏢 Mega events & sub-events

fest = vh.events.get("evt_mega_fest_2026")

if fest.event_type == "megaEvent":
    print(f"{fest.title} — {len(fest.sub_events or [])} sub-events")

    for sub in fest.sub_events or []:
        price = "Free" if sub.is_free else f"₹{sub.price}"
        print(f"  - {sub.title} ({price})")

        # Each sub-event has its own custom fields and tiers
        for field in sub.custom_fields or []:
            print(f"    * {field.name} [{field.type}]")

Register for a specific sub-event:

vh.events.register(
    "evt_sub_workshop_ml",
    RegisterData(name="Rahul", email="[e-mail]", phone="+91..."),
)

---

💳 Razorpay payment flow

Vihaya uses Razorpay under the hood. The flow:

1. Backend — vh.events.register(event_id, data) → Vihaya creates a Razorpay order and returns orderId.
2. Frontend — launch Razorpay Checkout with that orderId.
3. Razorpay callback — hands back razorpay_payment_id, razorpay_order_id, razorpay_signature.
4. Backend — vh.payments.verify(...) confirms the signature and marks the registration paid.

# Step 1: create order
result = vh.events.register("evt_conf_2026", RegisterData(
    name="Attendee", email="[e-mail]", phone="+91...",
))
order_id = result["orderId"]

# Step 2-3: (frontend) — Razorpay Checkout with order_id, get payment_id + signature

# Step 4: verify
vh.payments.verify(
    payment_id=razorpay_payment_id,
    order_id=razorpay_order_id,
    signature=razorpay_signature,
)

⚠️ Always verify payments on the server. A signature check performed only in the browser can be spoofed.

---

📖 API reference

Vihaya(api_key, *, base_url=..., headers=..., timeout=30.0)

The main client. All arguments after api_key are keyword-only.

Parameter	Type	Description
api_key	str	Required. Sent as the x-api-key header on every request.
base_url	str	Override for staging. Defaults to https://events.vihaya.app.
headers	dict	Extra headers attached to every request.
timeout	float	Per-request timeout in seconds. Default 30.

Context-manager supported: with Vihaya(...) as vh: releases the httpx connection pool on exit.

vh.events

Method	Returns	Description
list()	list[Event]	All events on the authenticated account.
get(event_id)	Event	Full metadata for one event — tiers, custom fields, speakers, agenda, sponsors, FAQs, sub-events.
register(event_id, data)	dict	Submit a registration. data can be RegisterData or a plain dict. Returns orderId (paid) or registrationId (free).

vh.payments

Method	Returns	Description
verify(*, payment_id, order_id, signature, amount=None)	dict	Server-side Razorpay signature verification. Raises VihayaError on mismatch.

---

🧬 Models

All models are Pydantic v2 models with extra="allow" — new fields the API adds between releases are preserved as extra attributes without requiring an SDK bump.

• Event — root event shape with all metadata
• Speaker — name, role, company, bio, photo_url
• Sponsor — name, tier, logo_url, website
• AgendaItem — time, title, description, speaker
• FAQItem — question, answer
• Contact — name, email, phone
• CustomField — name, type, required, options
• SpecialPrice — name, amount, description
• PromoCode — code, discount, discount_type
• RegisterData — registration payload (can also pass plain dict)

---

🚨 Error handling

All API failures raise VihayaError with the HTTP status and raw response body:

from vihaya import VihayaError

try:
    vh.events.get("evt_does_not_exist")
except VihayaError as exc:
    print(f"{exc.message} (status={exc.status})")
    print(exc.data)  # raw parsed JSON body, if any

Common status codes:

• 401 — missing or invalid API key
• 403 — insufficient permissions
• 404 — event/registration not found
• 409 — duplicate registration / capacity full
• 422 — validation error
• 429 — rate limited
• 500 — server error

---

🛡️ Security best practices

Never hard-code a vh_live_... key in source code.

• Use environment variables (VIHAYA_API_KEY), Django settings, AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault.
• Call events.register() and payments.verify() from backend code only — never from a browser, mobile app, or desktop client.
• Always verify Razorpay signatures on your server before trusting any payment_id.
• Rotate keys immediately in the Vihaya developer dashboard if you suspect a leak.
• Use separate keys for staging and production.

---

❓ FAQ

What is Vihaya?

Vihaya is an events platform for India — ticketing, registrations, payments, check-in, analytics, and attendee management for everything from college fests to corporate conferences. The platform lives at vihaya.app, the organiser dashboard at events.vihaya.app.

Is vihaya-events free?

Yes. The Python SDK is MIT-licensed. You only pay Vihaya platform fees when you sell tickets.

What's the difference between install name and import name?

You install with pip install vihaya-events but import with from vihaya import .... This is a common Python packaging pattern — it avoids colliding with the PyPI namespace while keeping imports short.

Does the SDK support async?

The current public interface is synchronous (built on httpx.Client). An async variant (vihaya.aio.Vihaya) is on the roadmap. For now, run sync calls in a thread pool executor or inside Celery tasks.

Does the Python SDK support the Razorpay test mode?

Yes — use a test API key from the Vihaya developer dashboard.

Can I use this with Jupyter, Streamlit, Dash, or Airflow?

Yes. The SDK is a plain Python package — works anywhere Python runs.

Can I pass a plain dict instead of RegisterData?

Yes. RegisterData is a convenience wrapper — dict works too, as long as you use camelCase keys (customFields, teamMembers, etc.).

---

🔎 Keywords

vihaya · vihaya sdk · vihaya events · vihaya events sdk · vihaya api · vihaya python · vihaya python sdk · vihaya-events · vihaya ticketing sdk · vihaya registration api · vihaya razorpay · events api python · event management sdk python · ticketing api python · college fest sdk · hackathon registration python · conference ticketing python · razorpay events python · django events sdk · flask events sdk · fastapi events sdk · events.vihaya.app python · vihaya official python sdk · vihaya client library python

---

🛠️ Development

git clone https://github.com/Vishnu252005/vihaya-sdk-python.git
cd vihaya-sdk-python
pip install -e ".[dev]"
pytest
ruff check .
mypy src

Pull requests welcome — see the contributing guide below.

---

🤝 Contributing

Contributions to the Vihaya Python SDK are very welcome. The project is open source and MIT-licensed.

1. Fork Vishnu252005/vihaya-sdk-python.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Run pytest, ruff check ., and mypy src to ensure the test suite still passes.
4. Commit and push.
5. Open a Pull Request.

Reporting issues

Found a bug or have a feature request? Open an issue at github.com/Vishnu252005/vihaya-sdk-python/issues.

---

📄 License

MIT © Vihaya. See LICENSE.

---

💬 Support

• 📧 Email: [e-mail]
• 🌐 Website: vihaya.app
• 🛠️ Dashboard: events.vihaya.app
• 👨‍💻 Developer docs: events.vihaya.app/profile/developer/docs
• 🐛 Issues: github.com/Vishnu252005/vihaya-sdk-python/issues

Built with ❤️ by the Vihaya team.

---

Related Vihaya SDK repositories

• Python: vihaya-sdk-python — you are here
• JavaScript / TypeScript: vihaya-sdk
• Go: vihaya-sdk-go
• Java: vihaya-sdk-java
• Ruby: vihaya-sdk-ruby
• PHP: vihaya-sdk-php
• Flutter: vihaya-sdk-flutter