> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

# Thena entity search API

Welcome to the Thena entity search API! This API provides powerful, flexible search capabilities across your core business data—tickets, accounts, and comments—using a unified, Typesense-powered interface.

## What can you do with Thena search?

* **Full-text search** across multiple collections
* **Advanced filtering** and faceting using Typesense syntax
* **Customizable field selection** for efficient, tailored responses
* **Sorting and pagination** for large result sets
* **Consistent, secure access** scoped to your organization and teams

## Supported collections

You can search the following collections:

* **tickets**: Support tickets, requests, or issues
* **accounts**: Customer or company accounts
* **comments**: Comments or notes attached to tickets or other entities
* **customer\_contacts**: (Contact support coming soon)

## Endpoint

```
GET /v1/search/{collection}
```

* **collection** (path parameter): The entity collection to search. Must be one of the supported collections above.

## Key query parameters

| Name             | Type   | Required | Description                                                                                   |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `q`              | string | Yes      | The search query string. Use `*` for a wildcard search.                                       |
| `query_by`       | string | Yes      | Comma-separated list of fields to search in (e.g. `title,description`).                       |
| `per_page`       | string | No       | Number of results per page. Default: 20.                                                      |
| `page`           | string | No       | Page number for pagination.                                                                   |
| `include_fields` | string | No       | Comma-separated list of fields to include in the response.                                    |
| `filter_by`      | string | No       | Filter expression using Typesense syntax (e.g. `priorityName:=medium&&statusName:=resolved`). |
| `sort_by`        | string | No       | Sort expression (e.g. `createdAt:desc`).                                                      |
| `streaming`      | bool   | No       | If `true`, enables streaming of paginated results.                                            |

> **Tip:** You can use any [Typesense search parameter](https://typesense.org/docs/0.24.0/api/documents.html#search-documents) for advanced use cases, including faceting, typo tolerance, and more.

***

## Streaming Results

Thena's search API supports streaming large result sets for improved performance and responsiveness. To enable streaming, add the `streaming=true` query parameter to your request.

* **How it works:**\
  When `streaming=true` is set, the API will stream each page of results as a separate JSON object. Each chunk is a full page of results, using the same structure as a normal (non-streaming) response.
* **Maximum page size:**\
  When streaming, the `per_page` parameter cannot exceed 250. If a higher value is provided, it will be capped at 250.
* **End of stream:**\
  The stream ends with a final chunk: `{ "done": true }`.
* **Error handling:**\
  If an error occurs during streaming, a chunk with `{ "error": "..." }` will be sent, and the stream will close.

### Example request

```bash theme={null}
curl -N -G \
  'https://api.thena.com/v1/search/tickets' \
  --data-urlencode 'q=*' \
  --data-urlencode 'query_by=title,description' \
  --data-urlencode 'per_page=100' \
  --data-urlencode 'streaming=true' \
  -H 'Authorization: Bearer <your_token>'
```

### Example streamed response

```
{ ...page 1 results... }
{ ...page 2 results... }
...
{ "done": true }
```

> **Note:** Each chunk is a full page of results in the same format as a normal search response. Process each chunk as it arrives for best performance.

#### Additional recommendations for developers

* **Process as you go:** Don't wait for the entire response—process each chunk as it arrives.
* **Respect per\_page limit:** If you request more than 250 results per page, only 250 will be returned per chunk.
* **Detect end of stream:** Always check for the `{ "done": true }` chunk to know when the stream is complete.
* **Handle errors:** Be prepared to handle a chunk with an `error` property.

***

Ready to get started? Explore the [detailed API reference for entity search](../platform/search/entity-search) to see available fields, example queries, and sample responses!

## Best practices

Follow these tips to get the most out of the Thena entity search API:

**Do:**

* Use the `include_fields` parameter to limit results to only the fields you need—this improves performance and reduces payload size.
* Use specific `query_by` fields relevant to your use case for more accurate results.
* Combine multiple filters in `filter_by` using `&&` for precise targeting (e.g. `status:=open&&priority:=high`).
* Use pagination (`per_page` and `page`) for large result sets to avoid timeouts and improve user experience.
* Use Typesense's advanced search parameters (faceting, typo tolerance, etc.) for complex needs.

**Don't:**

* Don't use `*` as your query unless you really want all results—prefer a more specific search string when possible.
* Don't request all fields unless necessary; avoid omitting `include_fields` for large collections.
* Don't use overly broad filters or sort expressions, as this can slow down search performance.
* Don't expose sensitive fields in your `include_fields` or query logic.

## Roadmap

The following features are coming soon:

* **Federated search** (search across multiple collections in a single query)
* **Vector/similarity search** (semantic and embedding-based search)