Which events you see

Your catalog is chosen by Blend, event by event. You never have to police it.

Blend hosts thousands of events for many organisers. Not all of them belong in your app, and deciding which ones do is not a job you should have to do yourself. So Blend does it: a member of our team adds each event to your listing, orders the list, marks the ones worth featuring, and switches any event off the moment it should no longer be sold through you. The API simply reflects those decisions.

The first half of this page is for whoever owns the commercial relationship: what control exists and where it is exercised. The second half is for whoever writes the integration: precisely what the API returns before, during and after a change.

For the business

Two ways a catalog can be scoped

Every partner account has a catalogScope. It is set by Blend and takes one of two values.

What a Blend admin controls

In the Blend admin console, under Channel Partners → your partner → Events, each event that has been added to your listing carries three controls. Together they are the whole of your catalog.

How an event reaches your storefront

1. The event is published on Blend

   The organiser creates it, sets it to Public, and Blend approves it. This is the same bar every event on Blend must clear; nothing partner-specific yet.

2. A Blend admin adds it to your listing

   Until this happens the event does not exist as far as your integration is concerned. There is no “public by default”: an event with no row in your listing is denied, not merely unsorted.

3. The admin switches it on, and optionally features and orders it

   It now appears in your list in the position the admin chose, and its detail page resolves.

4. The admin switches it off when it should stop

   It vanishes from your list and its detail page returns the same not-found response as an event that never existed. Nothing on your side needs to change.

To ask for an event to be added, removed, featured or moved, contact your Blend account manager. Changes made in the console take effect on the API without any action from you.

Powered by

For the engineer

The rules above reduce to a small table. In each row, “list” is GET /v1/channel/events and “detail” is GET /v1/channel/events/:id.

The general rules still apply

A listing row makes an event eligible. It is only returned if it also clears the platform-wide checks that apply under both scopes: the event is Public, approved by Blend, not cancelled, not deleted, and upcoming from the start of today. An enabled event that has passed, for example, is absent from the list even though its row is still switched on. Under all_events these checks are the only filter, which is why that scope is confined to staging.

Ordering, exactly

For a curated catalog the list is sorted by:

1. featured, featured first;
2. then sortOrder, as set by the admin;
3. then the event date, ascending.

Render the list in the order you receive it. The admin’s arrangement is the product; a client-side re-sort discards it.

Absence is denial

There is no field on any response that says “this partner may see this event”. Permission is expressed only by presence: an event you can sell is in your list and its detail resolves; one you cannot sell is not in your list and its detail is a 404. This is why the detail endpoint refuses to distinguish “not yours” from “does not exist”: doing so would leak the existence of every event you were not granted. The full reasoning is on Event detail & tickets.

curl "https://api.blendapp.ai/api/v1/channel/events" \
  -H "x-blend-key: ck_live_xxxxxxxx" \
  -H "x-blend-secret: cs_live_xxxxxxxx"

What this means for your code

• Treat the list as the source of truth, and re-read it. Anything you have stored that no longer appears has been switched off, cancelled or has passed. A periodic reconcile is simpler and more correct than trying to detect individual removals.
• Never hard-code an event identifier. Deep links and promotional placements should go through the detail endpoint and handle 404 as a normal outcome, not an incident.
• Do not cache the list in a shared cache. The response is per-partner and is marked Cache-Control: private, no-store and Vary: x-blend-key for that reason. Keep any cache inside your own service.
• Expect the list to change without a deploy on your side. It is edited by people in a console, not by a release.

// Re-read the catalog on a schedule and reconcile your own store against it.
// Anything missing from the list has been switched off, cancelled, or has passed.
async function syncCatalog(store) {
  const headers = {
    'x-blend-key': 'ck_live_xxxxxxxx',
    'x-blend-secret': 'cs_live_xxxxxxxx',
  };

  const seen = new Set();
  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();

    for (const card of body.data.events) {
      seen.add(card.id);
      store.upsert(card);          // keep the position: the list is already in Blend's order
    }
    pages = body.pagination.pages;
    page += 1;
  } while (page <= pages);

  store.removeWhere((card) => !seen.has(card.id));
}

Next