---
title: "Search"
method: POST
path: "/api/v1/events/search"
tags: ["event-search"]
---

# Search

`POST /api/v1/events/search`

## Request

- Base URL: `https://api.intentlink.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.intentlink.io/api/v1/events/search`
- Auth: none declared

Search ticketing/events and get ranked event bundles. Only ``query`` is required. Each
result's ``sessions[]`` (and ``matched_sessions[]`` when a date filter was given) carries a
per-date ``buy_url`` — a ready-to-use trackable link (CJ sid + redirect-wrapped) — hand it to
the buyer directly. ``landing_url`` is the plain event page.

## Request body

- EventSearchRequest: Event search request. Only ``query`` is required; the rest narrows recall/filtering.
  - `query` string, required: Natural-language intent, e.g. 'taylor swift concert near LA this summer'.
  - `keywords` string[]: Exact terms — performer / team / show / venue. Signals a precise lookup (BM25-leaning). Prefer a specific noun phrase over a bare generic word.
  - `categories` string[]: Category filter, e.g. 'Concerts' / 'Sports' / 'Theater' (L1) or a full category-path level. Read GET /events/categories for valid values.
  - `city` string, nullable: City name, e.g. 'Los Angeles'.
  - `state` string, nullable: US state abbreviation, e.g. 'CA'.
  - `country` string
  - `date_from` string, date, nullable: Earliest event date (YYYY-MM-DD).
  - `date_to` string, date, nullable: Latest event date (YYYY-MM-DD).
  - `when` 'this_weekend' | 'this_week' | 'this_month' | 'next_7_days' | 'next_30_days': Fuzzy-time helper. Expanded server-side to a ``date_from``/``date_to`` window (explicit ``date_from``/``date_to`` always win). Weeks are Mon–Sun; all windows start no earlier than today (the feed only holds upcoming events).
  - `min_price` number, nullable
  - `max_price` number, nullable
  - `sort` 'relevance' | 'soonest' | 'cheapest': Result ordering. ``relevance`` (default) is text-match first with a soonest tie-break; ``soonest`` sorts by the next upcoming date; ``cheapest`` by the lowest 'from' price.
  - `caller` Caller, required
    - `agent_id` string, required
    - `developer_id` string, nullable
    - `agent_name` string, nullable
    - `agent_version` string, nullable
    - `developer_account_id` string, nullable
    - `app_id` string, nullable
    - `integration_id` string, nullable
  - `tracking` TrackingContext
    - `agent_session_id` string, nullable
    - `end_user_id_hash` string, nullable
    - `sub_id` string, nullable
    - `channel` string, nullable
  - `limit` integer

## Response `200`

Successful Response

- EventSearchResponse: Event search response. ``status`` is "ok" for results, "no_results" when nothing matched, "error" for a rejected agent / backend failure (see ``errors``).
  - `request_id` string, required
  - `status` string, required
  - `query` string, nullable
  - `results` EventResult[]
    - `bundle_id` string, required
    - `title` string, required
    - `performers` string[]
    - `category_path` string[]
    - `category_l1` string, nullable
    - `category_l2` string, nullable
    - `venue_name` string, nullable
    - `city` string, nullable
    - `state` string, nullable
    - `country` string, nullable
    - `next_date` string, date, nullable
    - `date_from` string, date, nullable
    - `date_to` string, date, nullable
    - `price_min` number, nullable
    - `price_max` number, nullable
    - `currency` string, nullable
    - `session_count` integer
    - `sessions` EventSession[]
      - `date` string, date, required
      - `price_amount` number, nullable
      - `buy_url` string, nullable
      - `landing_url` string, nullable
      - `source_event_id` string, nullable
    - `matched_sessions` EventSession[]
      - `date` string, date, required
      - `price_amount` number, nullable
      - `buy_url` string, nullable
      - `landing_url` string, nullable
      - `source_event_id` string, nullable
    - `why` string, nullable
    - `score` number, nullable
  - `best` EventResult: One event bundle (a show run at a venue/city), with per-date ``sessions``.
    - `bundle_id` string, required
    - `title` string, required
    - `performers` string[]
    - `category_path` string[]
    - `category_l1` string, nullable
    - `category_l2` string, nullable
    - `venue_name` string, nullable
    - `city` string, nullable
    - `state` string, nullable
    - `country` string, nullable
    - `next_date` string, date, nullable
    - `date_from` string, date, nullable
    - `date_to` string, date, nullable
    - `price_min` number, nullable
    - `price_max` number, nullable
    - `currency` string, nullable
    - `session_count` integer
    - `sessions` EventSession[]
      - `date` string, date, required
      - `price_amount` number, nullable
      - `buy_url` string, nullable
      - `landing_url` string, nullable
      - `source_event_id` string, nullable
    - `matched_sessions` EventSession[]
      - `date` string, date, required
      - `price_amount` number, nullable
      - `buy_url` string, nullable
      - `landing_url` string, nullable
      - `source_event_id` string, nullable
    - `why` string, nullable
    - `score` number, nullable
  - `total_found` integer, nullable
  - `attribution` Attribution
    - `attribution_id` string, required
    - `click_id` string, required
    - `agent_id` string, required
    - `developer_id` string, nullable
    - `developer_account_id` string, nullable
    - `revenue_share_policy_id` string, nullable
    - `settlement_status` 'pending_click' | 'pending_conversion' | 'eligible' | 'rejected' | 'paid'
  - `agent_message` string, required
  - `reason` string, nullable
  - `errors` object[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/intentlink/apis/affiliate-recommendation-service.md) · [All operations](https://skmtc.dev/intentlink/apis/affiliate-recommendation-service/llms.txt) · [OpenAPI document](https://skmtc.dev/intentlink/apis/affiliate-recommendation-service/revisions/95cc11d55fb6?raw)