Events

Events are the core resource of the Qariyb platform. Use these endpoints to retrieve event listings and detailed information including tickets, features, and registration settings.

GET/api/v1/events

List all events

Retrieve a paginated list of your events. Returns a compact summary for each event.

Query parameters

Name
state
Type
string
Description
Filter by state: draft, preview, published, cancelled, completed.
Name
page
Type
integer
Description
Page number for pagination.
Name
per_page
Type
integer
Description
Events per page (1–20, default 15). A value above 20 is rejected with HTTP 422 rather than silently clamped, so read the error instead of assuming you received 20.

Request

GET

/api/v1/events

curl -G https://api.qariyb.com/api/v1/events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Accept: application/json" \
  -d state=published

Response

{
  "success": true,
  "code": 100,
  "locale": "en",
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "01HWX9KPQR5T7V8MNCBDJ3GFYZ",
        "title": "Community Iftar Dinner",
        "slug": "community-iftar-dinner",
        "summary": "Join us for a blessed evening of community iftar...",
        "public_url": "https://qariyb.com/discover/events/community-iftar-dinner",
        "state": "published",
        "visibility": "public",
        "pricing_model": "paid",
        "currency": "USD",
        "start_date": "2025-03-15",
        "start_time": "18:30:00",
        "end_date": "2025-03-15",
        "end_time": "21:30:00",
        "timezone": "America/New_York",
        "start_datetime_utc": "2025-03-15T22:30:00+00:00",
        "end_datetime_utc": "2025-03-16T01:30:00+00:00",
        "is_online": false,
        "location": "New York",
        "has_tickets": true,
        "requires_registration": true,
        "category": {
          "id": "01HWX9CAT123",
          "name": "Community",
          "slug": "community"
        },
        "cover_image": {
          "url": "https://qariyb.com/storage/events/iftar.jpg",
          "alt_text": "Community Iftar Dinner"
        },
        "created_at": "2025-01-10T14:30:00+00:00",
        "updated_at": "2025-02-20T09:15:00+00:00"
      }
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3
  }
}

GET/api/v1/events/:id

Retrieve an event

Retrieve the full details of a specific event including tickets, features, address, and registration settings.

Path parameters

Name
id
Type
string
Description
The unique ULID identifier of the event.

Response fields

Core

id - Unique ULID identifier
title, slug, summary, description
public_url - Full URL to the event's public page

State

state - draft, preview, published, cancelled, completed
visibility - public, private
pricing_model - free, paid, external
currency - ISO 4217 code, e.g. USD, GBP (null when pricing_model is not paid)

Date and Time

start_date, end_date - YYYY-MM-DD format
start_time, end_time - HH:mm:ss format
timezone - IANA identifier
start_datetime_utc, end_datetime_utc - ISO 8601

Location

is_online - Boolean
virtual_url, virtual_platform - Always present; both are null for an in-person event
address - Object with venue_name, line1, line2, city, state, postal_code, country, latitude, longitude, full_address, display_address

Registration

has_tickets, requires_registration, requires_approval, registration_open - Booleans
max_attendees - Integer or null
is_sold_out - Boolean, true when all active tickets are unavailable
external_registration_url - String or null

Relationships

category - id, name, slug
organizer - id, name
organization - id, name, slug, logo, is_verified
cover_image - url, alt_text

Collections

ticket_types[] - id, name, description, price_cents, currency, quantity, quantity_sold, is_available, is_free, max_per_order, min_per_order, sale_start_date, sale_end_date
features[] - name, slug, category
tags[] - name, slug, color
custom_questions[] - id, question, type, required, options, display_order

Request

GET

/api/v1/events/:id

curl https://api.qariyb.com/api/v1/events/01HWX9KPQR5T7V8MNCBDJ3GFYZ \
  -H "Authorization: Bearer sk_live_..." \
  -H "Accept: application/json"

Response

{
  "success": true,
  "code": 100,
  "locale": "en",
  "message": "OK",
  "data": {
    "id": "01HWX9KPQR5T7V8MNCBDJ3GFYZ",
    "title": "Community Iftar Dinner",
    "slug": "community-iftar-dinner",
    "summary": "Join us for a blessed evening...",
    "description": "<p>Full description with HTML formatting...</p>",
    "public_url": "https://qariyb.com/discover/events/community-iftar-dinner",
    "state": "published",
    "visibility": "public",
    "pricing_model": "paid",
    "currency": "USD",
    "start_date": "2025-03-15",
    "start_time": "18:30:00",
    "end_date": "2025-03-15",
    "end_time": "21:00:00",
    "timezone": "America/New_York",
    "start_datetime_utc": "2025-03-15T22:30:00+00:00",
    "end_datetime_utc": "2025-03-16T01:00:00+00:00",
    "is_online": false,
    "virtual_url": null,
    "virtual_platform": null,
    "address": {
      "venue_name": "Islamic Center",
      "line1": "123 Main Street",
      "line2": "Suite 100",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US",
      "latitude": 40.7128,
      "longitude": -74.006,
      "full_address": "123 Main Street, Suite 100, New York, NY 10001, US",
      "display_address": "Islamic Center, New York, NY"
    },
    "has_tickets": true,
    "requires_registration": true,
    "requires_approval": false,
    "registration_open": true,
    "max_attendees": 200,
    "is_sold_out": false,
    "external_registration_url": null,
    "is_recurring": false,
    "category": {
      "id": "01HWX9CAT123",
      "name": "Community",
      "slug": "community"
    },
    "organizer": {
      "id": "01HWX9USER123",
      "name": "Ahmad Hassan"
    },
    "organization": {
      "id": "01HWX9ORG123",
      "name": "Islamic Center of NY",
      "slug": "islamic-center-ny",
      "logo": "https://qariyb.com/storage/orgs/logo.png",
      "is_verified": true
    },
    "cover_image": {
      "url": "https://qariyb.com/storage/events/iftar.jpg",
      "alt_text": "Community Iftar Dinner"
    },
    "ticket_types": [
      {
        "id": "01HWX9TKT123",
        "name": "General Admission",
        "description": "Standard entry ticket",
        "price_cents": 2500,
        "currency": "USD",
        "quantity": 200,
        "quantity_sold": 95,
        "is_available": true,
        "is_free": false,
        "max_per_order": 10,
        "min_per_order": 1,
        "sale_start_date": "2025-01-01T00:00:00+00:00",
        "sale_end_date": "2025-03-15T18:00:00+00:00"
      }
    ],
    "features": [
      {
        "name": "Halal Food",
        "slug": "halal_food",
        "category": "dietary"
      },
      {
        "name": "Prayer Space",
        "slug": "prayer_space",
        "category": "prayer-worship"
      }
    ],
    "tags": [
      {
        "name": "Ramadan",
        "slug": "ramadan",
        "color": "#4CAF50"
      }
    ],
    "custom_questions": [
      {
        "id": "01HWX9Q001",
        "question": "Do you have any dietary requirements?",
        "type": "text",
        "required": false,
        "options": [],
        "display_order": 1
      },
      {
        "id": "01HWX9Q002",
        "question": "T-shirt size",
        "type": "select",
        "required": true,
        "options": [
          "S",
          "M",
          "L",
          "XL"
        ],
        "display_order": 2
      }
    ],
    "created_at": "2025-01-10T14:30:00+00:00",
    "updated_at": "2025-02-20T09:15:00+00:00"
  }
}

GET/api/v1/public/events/:id/availability

Check availability

Quick endpoint for widgets to check if an event is available for registration before showing the checkout UI. Uses widget key authentication (X-Widget-Key header).

Response attributes

Name
available
Type
boolean
Description
Whether the event is currently available for registration (not sold out and registration is open).
Name
event_id
Type
string
Description
The event ULID.
Name
registration_open
Type
boolean
Description
Whether the organizer has enabled registration.
Name
has_tickets
Type
boolean
Description
Whether the event has ticket types.
Name
is_sold_out
Type
boolean
Description
Whether all available tickets have been sold.
Name
total_tickets_available
Type
integer
Description
Total number of tickets still available across all ticket types.
Name
reason
Type
string | null
Description
Why the event is unavailable: event_not_found, event_not_available, sold_out, registration_closed, or null when available.

Request

GET

/api/v1/public/events/:id/availability

curl https://api.qariyb.com/api/v1/public/events/01HWX9KPQR/availability \
  -H "X-Widget-Key: pk_live_..." \
  -H "Accept: application/json"

Response (Available)

{
  "success": true,
  "code": 100,
  "locale": "en",
  "message": "OK",
  "data": {
    "available": true,
    "event_id": "01HWX9KPQR5T7V8MNCBDJ3GFYZ",
    "registration_open": true,
    "has_tickets": true,
    "is_sold_out": false,
    "total_tickets_available": 365,
    "reason": null
  }
}

Response (Sold Out)

{
  "success": true,
  "code": 100,
  "locale": "en",
  "message": "OK",
  "data": {
    "available": false,
    "event_id": "01HWX9KPQR5T7V8MNCBDJ3GFYZ",
    "registration_open": true,
    "has_tickets": true,
    "is_sold_out": true,
    "total_tickets_available": 0,
    "reason": "sold_out"
  }
}