Search API

The Search API provides global search functionality across tickets, customers, and knowledge base articles.

Search Result Object

{
  type: 'ticket' | 'customer' | 'article';
  id: string;                    // Entity UUID
  title: string;                 // Primary display text
  subtitle: string;              // Secondary display text
  href: string;                  // Link to entity detail page
  metadata?: object;             // Type-specific additional data
}

Global Search

Search across tickets, customers, and articles with full result details.

Procedure: search.global

Authentication: Required

Input:

{
  query: string;                                      // Search query (1-200 chars)
  types?: ('tickets' | 'customers' | 'articles')[];  // Entity types to search
  limit?: number;                                    // Results per type (1-20, default: 5)
}

Example:

curl -X GET "https://your-domain.com/api/trpc/search.global?input=%7B%22query%22:%22billing%20issue%22,%22limit%22:10%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "tickets": [
          {
            "type": "ticket",
            "id": "ticket-uuid",
            "title": "Billing issue with subscription",
            "subtitle": "#1234 - open",
            "href": "/dashboard/tickets/ticket-uuid",
            "metadata": {
              "status": "open",
              "priority": "high",
              "requester": {
                "name": "John Doe",
                "email": "john@example.com"
              }
            }
          }
        ],
        "customers": [
          {
            "type": "customer",
            "id": "customer-uuid",
            "title": "Jane Smith",
            "subtitle": "Billing Department",
            "href": "/dashboard/customers/customer-uuid",
            "metadata": {
              "email": "jane@billing.com",
              "status": "active",
              "totalTickets": 5
            }
          }
        ],
        "articles": [
          {
            "type": "article",
            "id": "article-uuid",
            "title": "How to Update Billing Information",
            "subtitle": "Billing & Payments",
            "href": "/dashboard/articles/article-uuid",
            "metadata": {
              "status": "published",
              "collection": "Billing & Payments"
            }
          }
        ],
        "total": 3
      }
    }
  }
}

Search Fields by Type

Permissions

• Tickets: All authenticated users
• Customers: Agents and Admins only
• Articles: All authenticated users

Quick Search

Lightweight search optimized for autocomplete, returns minimal ticket data.

Procedure: search.quick

Authentication: Required

Input:

{
  query: string;    // Search query (1-100 chars)
  limit?: number;   // Max results (1-10, default: 8)
}

Example:

curl -X GET "https://your-domain.com/api/trpc/search.quick?input=%7B%22query%22:%221234%22%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "type": "ticket",
          "id": "ticket-uuid",
          "title": "Help with order",
          "subtitle": "#1234",
          "href": "/dashboard/tickets/ticket-uuid"
        },
        {
          "type": "ticket",
          "id": "ticket-uuid-2",
          "title": "Order #12345 not delivered",
          "subtitle": "#1235",
          "href": "/dashboard/tickets/ticket-uuid-2"
        }
      ]
    }
  }
}

Notes:

• Searches ticket subjects and ticket numbers
• Optimized for fast response time
• Used by the command palette (Cmd+K)

Use Cases

Command Palette Search

// Debounced search as user types
const handleSearch = useDebouncedCallback(async (query: string) => {
  if (query.length < 1) return

  const results = await trpc.search.quick.query({
    query,
    limit: 8,
  })

  setResults(results)
}, 150)

Full Search Page

// Search across all entity types
const { tickets, customers, articles, total } =
  await trpc.search.global.query({
    query: searchTerm,
    types: ['tickets', 'customers', 'articles'],
    limit: 10,
  })

// Display grouped results
<SearchResults>
  <Section title="Tickets" items={tickets} />
  <Section title="Customers" items={customers} />
  <Section title="Articles" items={articles} />
</SearchResults>

Filtered Search

// Search only tickets
const { tickets } = await trpc.search.global.query({
  query: 'refund request',
  types: ['tickets'],
  limit: 20,
})

Error Codes