Listing events

One request returns the events you are allowed to sell, ready to render as a list.

Every partner has a catalog: the set of events Blend has switched on for them. This endpoint returns that catalog as a list of compact cards, twenty at a time, each with enough information to draw a tile in your app: a title, a cover image, the date, the venue, and the lowest ticket price. Nothing appears here that you have not been granted, and nothing appears that a customer could not actually buy today.

When a customer taps a card, fetch the full event with Event detail & tickets. To understand how the catalog itself is decided, see Which events you see.

Requires the catalog.read scope. Send both credentials on every call; the base URL is https://api.blendapp.ai/api/v1.

Query parameters

All parameters are optional. With none, you get the first twenty upcoming events in catalog order.

Request

curl "https://api.blendapp.ai/api/v1/channel/events?page=1&limit=20" \
  -H "x-blend-key: ck_live_xxxxxxxx" \
  -H "x-blend-secret: cs_live_xxxxxxxx"

Response

A successful call returns 200 with the standard envelope. The cards live in data.events; paging information sits alongside in pagination. Values below are illustrative.

{
  "success": true,
  "code": null,
  "message": null,
  "data": {
    "events": [
      {
        "id": "8fK3qLp",
        "shortId": "8fK3qLp",
        "slug": "beirut-jazz-night",
        "title": "Beirut Jazz Night",
        "coverImageUrl": "https://images.example.com/8fK3qLp/cover.jpg",
        "startDate": "2026-10-03T00:00:00.000Z",
        "endDate": "2026-10-03T00:00:00.000Z",
        "startTime": "20:00",
        "timezone": "Asia/Beirut",
        "venue": "Music Hall, Beirut",
        "category": "Music",
        "currency": "USD",
        "priceFrom": 25,
        "soldOut": false,
        "lowStock": false
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 37,
    "pages": 2
  }
}

The event card

Each entry in data.events has exactly these fields. The card is deliberately small: it is what you need to draw a list, not the full event, so the list stays fast even at fifty cards a page.

Pagination

// Walk every page of the catalog. Stop when pagination.pages is reached.
async function fetchAllEvents() {
  const headers = {
    'x-blend-key': 'ck_live_xxxxxxxx',
    'x-blend-secret': 'cs_live_xxxxxxxx',
  };
  const events = [];
  let page = 1;
  let pages = 1;

  do {
    const url = new URL('https://api.blendapp.ai/api/v1/channel/events');
    url.searchParams.set('page', String(page));
    url.searchParams.set('limit', '50');

    const res = await fetch(url, { headers });
    const body = await res.json();

    events.push(...body.data.events);
    pages = body.pagination.pages;
    page += 1;
  } while (page <= pages);

  return events;
}

Filtering

Filters combine: a request with city, from and to returns only events in that city inside that date window. search is the only fuzzy parameter; category is an exact match, so use the value you were given in a card rather than a guess.

# Everything in Beirut during October, 50 per page
curl "https://api.blendapp.ai/api/v1/channel/events?city=Beirut&from=2026-10-01&to=2026-10-31&limit=50" \
  -H "x-blend-key: ck_live_xxxxxxxx" \
  -H "x-blend-secret: cs_live_xxxxxxxx"

What is included

An event has to clear every one of these before it can appear in your list. There is no parameter to bypass any of them.

• It is in your catalog and switched on (see Which events you see).
• Its visibility is Public.
• It has been approved by Blend.
• It has not been cancelled.
• It has not been deleted.
• It is upcoming: on or after the start of today.

Ordering

A curated catalog is returned in the order Blend arranged it for you, which is what you should show. The sort is, in priority order:

1. Featured events first.
2. Then the sort order a Blend admin set for your listing.
3. Then event date, soonest first.

The response does not carry a separate featured flag; the position in the list is the signal. If you re-sort client-side (by date, say), you lose the arrangement Blend made for you.

Powered by

Caching

Every response carries two headers that you should leave alone.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-store
Vary: x-blend-key

The reason is simple: the list is yours. Two partners calling the same URL with different keys receive different catalogs. A CDN, a corporate proxy or a shared application cache that keyed on the URL alone would hand one partner’s catalog to another.

• Cache-Control: private, no-store tells every shared cache between you and Blend not to store the body at all.
• Vary: x-blend-key tells any cache that does store it that the key is part of the identity of the response, so one partner’s copy can never satisfy another’s request.

Rate limit

This endpoint allows 600 requests per minute per key. A list of fifty cards is a single request, so a full crawl of even a large catalog is a handful of calls; a per-user poll on every app launch is not what the limit is for. See Rate limits for how a limit is signalled.

Next