Organizations

The Organizations API provides access to published events for a specific organization. This endpoint is available through the public widget API using widget key authentication.

This endpoint uses publishable widget key authentication (X-Widget-Key header), not the secret key used by the REST API. It is designed for embedded widgets on third-party websites.

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

List organization events

Retrieve a list of published events for an organization. Returns events formatted for widget embedding with ticket availability and feature information.

Path parameters

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

Query parameters

Name
limit
Type
integer
Description
Maximum number of events to return (1–50, default 10). Out-of-range values are clamped, not rejected.
Name
offset
Type
integer
Description
Zero-based offset into the result set (default 0). Combine with limit to page through events.
Name
include_past
Type
boolean
Description
Include events with past end dates (default: false). When false, only returns events with future end dates or no end date set.

Response

Returns an array of events using the same format as the public event details endpoint. Each event includes ticket types, features, cover image, and registration settings.

Pagination headers

Paging metadata travels in response headers rather than the body, so the body stays a plain array:

Header	Meaning
`X-Total-Count`	Total events matching the query, ignoring `limit`/`offset`
`X-Offset`	The offset that was applied
`X-Limit`	The limit that was applied

A browser can only read these cross-origin if the API lists them in Access-Control-Expose-Headers. When they are unreadable, treat the total as unknown rather than zero — @qariyb/js returns null for each in getOrganizationEventsPage() for exactly this reason.

A key may only list its own organization's events. Requesting another organization's ULID returns 404, not 403, so the response cannot be used to discover which organization ULIDs exist.

Request

GET

/api/v1/public/organizations/:id/events

curl -G https://api.qariyb.com/api/v1/public/organizations/01HWX9ORG123/events \
  -H "X-Widget-Key: pk_live_..." \
  -H "Accept: application/json" \
  -d limit=5

Response

{
  "success": true,
  "code": 100,
  "locale": "en",
  "message": "OK",
  "data": {
    "item": [
      {
        "id": "01HWX9KPQR5T7V8MNCBDJ3GFYZ",
        "title": "Community Iftar Dinner",
        "slug": "community-iftar-dinner",
        "summary": "Join us for a blessed evening...",
        "description": "<p>Full description...</p>",
        "pricing_model": "paid",
        "currency": "GBP",
        "start_date": "2026-06-16",
        "start_time": "18:30:00",
        "end_date": "2026-06-16",
        "end_time": "21:00:00",
        "timezone": "Europe/London",
        "start_datetime_utc": "2026-06-16T17:30:00+00:00",
        "end_datetime_utc": "2026-06-16T20:00:00+00:00",
        "is_online": false,
        "virtual_platform": null,
        "address": {
          "venue_name": "Al-Noor Islamic Centre",
          "city": "London",
          "state": null,
          "country": "GB",
          "display_address": "Al-Noor Islamic Centre, London, GB"
        },
        "has_tickets": true,
        "requires_registration": true,
        "requires_approval": false,
        "registration_open": true,
        "is_sold_out": false,
        "category": {
          "name": "Ramadan & Eid Events",
          "slug": "ramadan-eid-events"
        },
        "organization": {
          "name": "Al-Noor Islamic Centre",
          "slug": "al-noor-islamic-centre",
          "logo": null,
          "is_verified": false
        },
        "cover_image": {
          "url": "https://qariyb.com/storage/events/iftar.jpg",
          "alt_text": "Community Iftar Dinner"
        },
        "ticket_types": [
          {
            "id": "01HWX9TKT123",
            "name": "Individual Ticket",
            "description": "Single person ticket",
            "price_cents": 1500,
            "currency": "GBP",
            "quantity_available": 172,
            "max_per_order": 8,
            "min_per_order": 1,
            "is_free": false
          }
        ],
        "features": [
          { "name": "Halal Food", "slug": "halal_food", "category": "dietary" }
        ],
        "public_url": "https://qariyb.com/discover/events/01HWX9KPQR5T7V8MNCBDJ3GFYZ"
      }
    ]
  }
}

Error (Organization Not Found)

{
  "success": false,
  "code": 203,
  "locale": "en",
  "message": "Resource not found",
  "data": null
}

Error handling

HTTP	ApiCode	Scenario	Action
401	600	Missing widget key header	Include `X-Widget-Key` header
401	601	Invalid or inactive widget key	Check your publishable key
403	604	Origin domain not allowed	Add domain to widget key's allowed domains
404	203	Organization not found	Check the organization ULID
429	605	Rate limit exceeded	Reduce request frequency (120/min per key)

View all error codes