PrimeCal Calendar Events Search v2

primecal_calendars_events_search_v2 performs server-side keyword search across event titles and descriptions while preserving the v2 compact event shape.

On PostgreSQL 11 and newer, PrimeCal uses typed websearch_to_tsquery-based full-text search. On older PostgreSQL versions, or on deployments where that function is unavailable, the tool safely falls back to server-side ILIKE matching instead of failing.

Request Parameters

Field	Type	Required	Notes
query	string	Yes	Free-text search query. Max 200 characters.
calendarIds	number[]	No	Optional subset of accessible calendars.
from	string	No	Optional ISO 8601 UTC lower bound.
to	string	No	Optional ISO 8601 UTC upper bound.
verbosity	string	No	compact or full. Default compact.
fields	string[]	No	Extra fields to include.
includeFullDescription	boolean	No	Default false.
limit	number	No	Default 50, max 200.
cursor	string	No	Opaque pagination token.
userTimezone	string	No	Optional logical timezone override, used for timezone and startsAtLocal / endsAtLocal. Falls back to the caller's profile timezone, then UTC.

Response Additions

Search responses always include the normal v2 event fields plus:

• matchedField
  • title when the best hit is in the title
  • description when the best hit is in the description

Responses also include:

• items
• timezone
• totalCount
• truncated
• nextCursor

Ordering

PrimeCal sorts search results by:

1. Full-text relevance when available, otherwise title-first substring relevance
2. startsAt ascending as a deterministic fallback
3. id ascending as the final tie-breaker

Example

{
  "items": [
    {
      "id": 91,
      "title": "May kickoff",
      "startsAt": "2032-04-16T07:00:00.000Z",
      "endsAt": "2032-04-16T08:00:00.000Z",
      "startsAtLocal": "2032-04-16T09:00:00+02:00",
      "endsAtLocal": "2032-04-16T10:00:00+02:00",
      "calendarId": 14,
      "calendarName": "May.B.Late Personal",
      "meetingUrl": "https://meet.google.com/abc-defg-hij",
      "matchedField": "description",
      "timezone": "Europe/Budapest"
    }
  ],
  "timezone": "Europe/Budapest",
  "totalCount": 1,
  "truncated": false,
  "nextCursor": null
}

Notes

• instanceDate is reliably non-null for expanded recurrence instances in search results (same fix as in primecal_calendars_events_list). See PrimeCal Calendar Events List v2 for details.
• Search stays server-side and uses database search primitives rather than in-memory scans.
• PrimeCal binds the search text as text, so websearch_to_tsquery overload resolution does not depend on PostgreSQL inferring unknown parameters.
• Search prefers websearch_to_tsquery('simple'::regconfig, $1::text) when the database supports it and falls back to ILIKE when it does not.
• Query validation rejects empty or punctuation-only input.
• New clients should prefer from and to over the deprecated start and end aliases.
• Older PostgreSQL versions no longer surface a 500 error for this tool just because websearch_to_tsquery is unavailable.

Typical Error Handling

• invalid input: validation error before the database query runs
• unsupported or older PostgreSQL search function: PrimeCal falls back to ILIKE
• empty result: successful response with items: []

Screenshot Reference